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NAME 

intro - introduction to commands 
DESCRIPTION 

This section describes publicly accessible commands in alphabetic order. Certain distinctions of pur¬ 
pose are made in the headings: 

(1) Commands of general utility. 

(IQ Commands for communication with other systems. 

(IG) Commands used primarily for graphics and computer-aided design. 

(IW) EUNICE specific commands. 

N.B.: Commands related to system maintenance used to appear in section 1 manual pages and were dis¬ 
tinguished by (IM) at the top of the page. These manual pages now appear in section 8. 

EUNICE NOTES 

In contrast to previous releases of Wollongong’s EUNICE p-oduct, pages have NOT been included in 
the Programmer’s Manual for certain User Contributed Software commands which are presently una¬ 
vailable under EUNICE. For a complete list of commands not supported, please refer to the EUNICE 
BSD Reference Manual. 

Certain commands exhibit altered characteristics due to VMS’s being the host opiating system. Wher¬ 
ever possible, the manual pages involved have been changed to include a section (like this one) entitled 
"EUNICE NOTES" - which contains any appropriate caveats. 

Background processes terminate at logout. 

SEE ALSO 

Section (6) for computer games. 

How to get started, in the Introduction. 

DIAGNOSTICS 

Upon termination each command returns two bytes of status, one supplied by the system giving the 
cause ftxr termination, and (in the case of ‘normal’ termination) one supplied by the program, see wait 
and exit (2). The former byte is 0 for normal termination, the latter is customarily 0 for successful exe¬ 
cution, nonzero to indicate troubles such as erroneous parameters, bad or inaccessible data, or other ina¬ 
bility to cope with the task at hand. It is called variously ‘exit code’, ‘exit status’ or ‘return code’, and 
is described only where special conventions are involved. 
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NAME 

adb - debugger 
SYNOPSIS 

adb [-W] [ -k ] [ -Idir ] [ objfil [ corfil ] ] 

DESCRIPTION 

Adb is a general purpose debugging program. It may be used to examine files and to provide a con¬ 
trolled environment for the execution of UNIX programs. 

Objfil is normally an executable program file, preferably containing a symbol table; if not then the sym¬ 
bolic features of adb cannot be used although the file can still be examined. The default for objfil is 
a.out. Corfil is assumed to be a core image file produced after executing objfil; the default for corfil is 

core. 

Requests to adb are read from the standard input and responses are to the standard output If the -w 
flag is present then both objfil and corjU are created if necessary and opened for reading and writing so 
that files can be modified using adb. 

The -k option makes adb do UNIX kernel memory mapping; it should be used when core is a UNIX 
crash dump or Idevirrtem. 

The -I option specifies a directory where files to be read with $< or $« (see below) will be sought; the 
default is lusrilibladb. 

Adb ignores QUIT; INTERRUPT causes return to the next adb command. 

In general requests to adb arc of the form 

[ address ] [, count ] [ command] [; ] 

If address is present then dbr is set to address. Initially dot is set to 0. For most commands count 
specifies how many times the command will be executed. The default count is 1. Address and count 
are expressions. 

The interpretation of an address depends on the context it is used in. If a subprocess is being debugged 
then addresses are intopreted in the usual way in the address space of the subprocess. If the operating 
system is being debug^ either post-mortem or using the special file Idevimem to interactive examine 
and/or modify memory the maps are set to map the kernel virtual addresses which start at 0x80000000 
(on the VAX). ADDRESSES. 

EXPRESSIONS 

. The value of dot. 

+ The value of dot incremented by the current increment. 

TTie value of dot decremented by the current increment. 

" The last address typed. 

integer A number. The prefixes Oo and OO (“zero oh”) force interpretation in octal radix; the prefixes 
Ot and OT force interpretation in decimal radix; the prefixes Ox and OX force interpretation in 
hexadecimal radix. Thus 0o20 = 0tl6 = 0x10 = sixteen. If no prefix appears, then the 
d^ault radix is used; see the $d command. The default radix is initially hexadecimal. The 
hexadecimal digits are 0123456789abcdefABCDEF with the obvious values. Note that a hexa¬ 
decimal number whose most significant digit would otherwise be an alphabetic character must 
have a Ox (or OX) prefix (or a leading zero if the default radix is hexadecimal). 

integer .fraction 

A 32 bit floating point number. 

'cccc ' The ASCII value of up to 4 characters. \ may be used to escape a '. 

< name The value of name, which is either a variable name or a register name. Adb maintains a 
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number of variables (see VARIABLES) named by single letters or digits. If name is a register 
name then the value of the register is obtained from the system header in corfil. The register 
names are those printed by the $r command. 

symbol A symbol is a sequence of upper or lower case letters, underscores or digits, not starting with a 
digit The backslash character \ may be used to escape other characters. The value of the 
symbol is taken from the symbol table in objfil. An initial _ will be prepended to symbol if 
needed. 

_ symbol 

In C, the ‘true name’ of an external symbol begins with _. It may be necessary to utter this 
name to distinguish it from internal ot hidden variables of a program. 

routine.name 

The address of the variable name in the specified C routine. Both routine and name are sym¬ 
bols. If ruune is omitted the value is the address of the most recently activated C stack frame 
corresponding to routine. (This form is currently broken on the VAX; local variables can be 
examined only with dbx(X).) 

(exp) The value of the expression ejq). 

Monadic operators ^ 

*exp The ccmtents of the location addressed by exp in corfil. 

@exp The ccHitents of the location addressed by exp in objfil. 

-exp Integer negation. 

~€xp Bitwise complement. 

#exp Logical negation. 

Dyadic operators are left associative and are less binding than monadic operators. 

el +e2 Integer addition. 

el-e2 Integer subtraction. 

el *e2 Integer multiplication. 

el %e2 IntegCT division. 

el &e2 Bitwise conjunction. 

el \e2 Bitwise disjunction. 

el^e2 El rounded up to the next multiple of e2. 

COMMANDS 

Most commands consist of a verb followed by a modifier or list of modifiers. The following verbs are 
available. (The commands *?’ and ‘/’ may be followed by see ADDRESSES for further details.) 

?/ Locations starting at address in objfil are printed according to the format/, dot is incremented 
by the sum of the increments for each format letter (q.v.). 

If Locations starting at address in corfil are printed according to the format / and dot is incre¬ 
mented as for *?’. 

=/ pie value of address itself is printed in the styles indicated by the format/. (For i format ‘?’ 
is printed for the parts of the instruction that reference subsequent words.) 

K format consists of one or more characters that specify a style of printing. Each format character may 
be preceded by a decimal integer that is a repeat count for the format character. While stepping 
through a format dot is incremented by the amount given for each format letter. If no format is given 
then the last format is used. The format letters available are as follows. 
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o 2 Print 2 bytes in octal. All octal numbers output by adb are preceded by 0. 

O 4 Print 4 bytes in octal, 

q 2 Print in signed octal. 

Q 4 Print long signed octal, 

d 2 Print in decimal. 

D 4 Print long decimal. 

X 2 Print 2 bytes in hexadecimal. 

X 4 Print 4 bytes in hexadecimal, 

u 2 Print as an unsigned decimal numb^. 

U 4 Print long unsigned decimal, 
f 4 Print the 32 bit value as a fleeting point number. 

F 8 Print double floating point 

b 1 Print the addressed byte in octal, 

c 1 Print the addressed character. 

C 1 Print the addressed characto' using the standard escape convention where control char¬ 
acters are printed as "X and the delete character is printed as"?. 
s n Print the addressed characters until a zero character is reached. 

S n Print a string using the escape convention (see C above), n is the length of the 

string including its zero terminator. 

Y 4 Print 4 bytes in date format (see ctime(3)). 

i n Print as machine instructions, n is the number of bytes occupied by the instruction. 
This style of printing causes variables 1 and 2 to be set to the offset parts of the 
source and destination respectively. 

a 0 Print the value of dot in symbolic form. Symbols are checked to ensure that they 
have an appropriate type as indicated below. 

/ local or global data symbol 

? local or global text symbol 

s local or global absolute symbol 

p 4 Print the addressed value in symbolic form using the same rules for symbol lookup as 
a. 

t 0 When preceded by an integer tabs to the next appropriate tab stop. For example, 8t 
moves to the next 8-space tab stop, 
r 0 Print a space, 

n 0 Print a newline. 

0 Print the enclosed string. 

Dot is decremented by tlw current increment. Nothing is printed. 

+ Dot is incremented by 1. Nothing is pinted. 

- Dot is decremented by 1. Nothing is printed. 

newline Repeat the previous command with a count of 1. 

[?/]l value mask 

Words starting at dot are masked with mask and compared with value until a match is found. 
If L is used then the match is for 4 bytes at a time instead of 2. If no match is found then dot 
is unchanged; otherwise dot is set to die matched location. If mask is omitted then -1 is used. 

[?/]w value ... 

Write the 2-byte value into the addressed location. If the command is W, write 4 bytes. Odd 
addresses are not allowed when writing to the subprocess address space. 

[?/]m bl el fl[V] 

New values for (bl. el.fl) are recorded. If less than three expressions are given then the 
remaining map parameters are left unchanged. If the *?’ or 7’ is followed by then the 
second segment (b2,e2,f2) of the mapping is changed. If the list is terminated by ‘?’ or V’ 
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then the file {objfil or corfil respectively) is used for subsequent requests. (So that, for exam¬ 
ple, 7m?’ will cause T to refer to objfil.) 

>name Dot is assigned to the variable or register named. 

! A shell (/bin/sh) is called to read the rest of the line following *!’. 

%modifier 

Miscellaneous commands. The available modifiers are: 

<f Read commands from the file /. If this command is executed in a file, further com¬ 
mands in the file are not seen. If/is omitted, the current input stream is terminated. 
If a count is given, and is zero, the command will be ignored. The value of the count 
will be placed in variable 9 before the first command in / is executed. 

«f Similar to < except it can be used in a file of commands without causing the file to be 

closed. Variable 9 is saved during the execution of this command, and restored when 
it completes. There is a (small) finite limit to the number of « files that can be open 
at once. 

>/ Append output to the file/, which is created if it does not exist. If/is omitted, output 
is returned to the terminal. 

? Print process id, the signal which caused stoppage or termination, as well as the regis¬ 
ters as $r. This is the default if modifier is omitted, 
r Print the general registers and the instruction addressed by pc. Dot is set to pc. 
b Print all breakpoints and their associated counts and commands, 

c C stack backtrace. If address is given then it is taken as the address of the current 

frame instead of the contents of the frame-pointer register. If C is used then the 
names and (32 bit) values of all automatic and static variables are printed for each 
active function, (broken on the VAX). If count is given then only the first count 
frames are printed. 

d Set the default radix to address and report the new value. Note that address is inter¬ 
preted in the (old) current radbc. Thus “10$d” never changes the default radix. To 
make decimal the default radix, use “OtlOSd”. 
e The names and values of external variables are printed, 
w Set the page width for output to address (default 80). 
s Set the limit for symbol matches to address (default 255). 
o All integers input are regarded as octal, 
q Exit from adb. 

V Print all non zero variables in octal, 

m Print the address map. 

p {Kernel debugging) Change the current kernel memory mapping to map the designated 
user structure to the address given by the symbol _u. The address argument is the 
address of the user’s user page table entries (on the VAX). 

'.modifier 

Manage a subprocess. Available modifiers are: 

be Set breakpoint at address. The breakpoint is executed count-l times before causing a 
stop. Each time the breakpoint is encountered the command c is executed. If this 
command is omitted or sets dot to zero then the breakpoint causes a stop. 

d Delete breakpoint at address. 

r Run objfil as a subprocess. If address is given explicitly then the program is entered 
at this point; otherwise the program is entered at its standard entry point count 
specifies how many breakpx}ints are to be ignored before stopping. Arguments to the 
subprocess may be supplied on the same line as the command. An argument starting 
with < or > causes the standard input or output to be established for the command. 
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cs The subprocess is continued with signal s, see sigvec{2). If address is given then the 
subprocess is continued at this address. If no signal is specified then the signal that 
caused the subprocess to stop is sent Breakpoint skipping is the same as for r. 

As for c except that the subprocess is single stepped count times. If there is no 
current subprocess then objfil is run as a subprocess as for r. In this case no signal 
can be sent; the remainder of the line is treated as arguments to the subprocess. 

k The current subprocess, if any, is terminated. 

VARIABLES 

Adb provides a number of variables. Named variables are set initially by adb but are not used subse¬ 
quently. Numbered variables are reserved for communication as follows. 

0 The last value printed. 

1 The last offset part of an instruction source. 

2 The previous value of variable 1. 

9 The count on the last $< or $« command. 

On entry the following are set from the system header in the corfil. If corfil does not appear to be a 
core file then these values are set from objil. 

b The base address of the data segment, 

d The data segment size, 

e The entry point. 

m The ‘magic’ number (0407, 0410 or 0413). 
s The stack segment size, 

t The text segment size. 

ADDRESSES 

The address in a file associated with a written address is determined by a mapping associated with that 
file. Each mapping is represented by two triples (bl, el, fl) and {b2, e2, f2) and the file address 
corresponding to a writtra address is calculated as follows. 

bl<£iddress<el => file address^=address+fl-bl, otherwise, 
b2<address<e2 ^ file address^=address+J2-d?2, 

otherwise, the requested address is not legal. In some cases (e.g. for programs with separated I and D 
space) the two segments for a file may overlap. If a ? ot / is followed by an * then only the second tri¬ 
ple is used. 

The initial setting of both mappings is suitable for normal a.out and core files. If either file is not of 
the kind expected then, fw that file, bl is set to 0, el is set to the maximum file size and fl is set to 0; 
in this way the whole file can be examined with no address translation. 

FILES 

a.out 

core 

SEE ALSO 

cc(l), dbx(l), ptrace(2), a.out(5), core(5) 

DIAGNOSTICS 

‘Adb’ when there is no current command or format. Comments about inaccessible files, syntax errors, 
abnormal termination of commands, etc. Exit status is 0, unless last command failed or returned 
nonzero status. 

BUGS 

Since no shell is invoked to interpret the arguments of the :r command, the customary wild-card and 
variable expansions cannot occur. 
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NAME 

addbib - create or extend bibliographic database 
SYNOPSIS 

addbib [ -p promptfile ] [ -a ] database 
DESCRIPTION 

When this program starts up, answering “y” to the initial “Instructions?” prompt yields directions; 
typing “n” or RETURN skips them. Addbib then prompts for various bibliographic fields, reads 
responses from the terminal, and sends output records to a database. A null response (just return) 
means to leave out that field. A minus sign (-) means to go back to the previous field. A trailing 
backslash allows a field to be continued on the next line. The repeating “Continue?” prompt allows 
the user either to resume by typing “y” or return, to quit the current session by typing “n” or “q”, 
or to edit the database with any system editor (vi, ex, edit, ed). 

The -a option suppresses prompting for an abstract; asking for an abstract is the default Abstracts are 
ended with a CTRL>d. The -p option causes addbib to use a new prompting skeleton, defined in 
promp^le. This file should contain prompt strings, a tab, and the key-letters to be written to the data¬ 
base. 

The most conunon key-letters and their meanings are given below. Addbib insulates you from these 
key-letters, since it gives you prompts in English, but if you edit the bibliography file later on, you will 
need to know this information. 

%A Author’s name 

%B Book containing article referenced 

%C City (place of publication) 

%D Date of publication 

%E Editor of book containing article referenced 

%F Foomote number or label (supplied by r^er) 

%G Government order number 

%H Head^ commentary, printed before reference 

%I Issuer (publisher) 

%J Journal containing article 

%K Keywords to use in locating reference 

%L La^l field used by -k option of refer 
%M Bell Labs Memorandum (undefined) 

%N Number within volume 

%0 Other commentary, printed at end of reference 

%P Page number(s) 

%Q Corporate or Foreign Author (uru'eversed) 

%R Report, paper, or thesis (unpublished) 

%S Series title 

%T Title of article or book 

%V Volume number 

%X Abstract — used by roffbib, not by refer 

%Y,Z ignored by refer 

Except for ‘A’, each field should be given just once. Only relevant fields should be supplied. An 
example is: 

%A Bill TuthUl 

%T Refer — A Bibliography System 

%I Computing Services 

%C Berkeley 
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%D 1982 

%0 UNX 4.3.5. 

FILES 

promptfile optional file to define prompting 

SEE ALSO 

refer(l), sortbib(l), roffbib(l), indxbib(l), lookbib(l) 
AUTHORS 

A1 Stangenberger, Bill Tuthill 
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NAME 

apply - apply a command to a set of arguments 
SYNOPSIS 

apply [ -ac ] [ -n ] command args ... 

DESCRIPTION 

Apply runs the named command on each argument arg in turn. Normally arguments are chosen singly; 
the optional number n specifies the number of arguments to be passed to command. If n is zero, com¬ 
mand is run without arguments once for each arg. Character sequences of the form %d in command, 
where d is a digit from 1 to 9, are replaced by the d’th following unused arg. If any such sequences 
occur, n is ignOTed, and the number of arguments passed to command is the maximum value of d in 
command. The character *%’ may be changed by the -a option. 

Examples: 

apply echo ♦ 
is similar to ls(l); 

apply -2 cmp al bl a2 b2 ... 
compares the ‘a’ files to the ‘b’ files; 

apply -0 who 1 2 3 4 5 
runs who(l) 5 times; and 

apply Tn %1 Aisr/joe' ♦ 

links all files in the current directory to the directory /usr/joe. 

SEE ALSO 

sh(l) 

AUTHOR 

Rob Pike 

BUGS 

Shell metacharacters in command may have bizarre effects; it is best to enclose complicated commands 
in single quotes ' 

There is no way to pass a literal ‘%2’ if is the argument expansion character. 
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NAME 

apropos - locate commands by keyword lookup 

SYNOPSIS 

apropos keyword... 

DESCRIPTION 

Apropos shows which manual sections contain instances of any of the given keywords in their title. 
Each word is considered separately and case of letters is ignored. Words which are part of other words 
are considered; thus, when loddng for compile, apropos will find all instances of ‘compiler’ also. Try 

apropos password 
and 

apropos editor 

If the line starts ‘name(section) ...’ you can do ‘man section name’ to get the documentation for it. Try 
‘apropos format’ and then ‘man 3s printf to get the manual on the subroutine printf. 

Apropos is actually just the -k option to the man{l) command. 

FILES 

/usr/man/whatis dam base 

SEE ALSO 

man(l), whatis(l), catman(8) 

AUTHOR 

William Joy 
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NAME 

ar - archive and library maintainer 

SYNOPSIS 

ar key [ posname ] afile name ... 

DESCRIPTION 

Ar maintains groups of files ctHnbined into a single archive file. Its main use is to create and update 
library files as used by the loader. It can be used, though, for any similar purpose. N.B: This version 
of ar uses a ASCII-format archive which is portable among the various machines running Unix. Pro¬ 
grams for dealing with older formats are available: see flrcv(8). 

Key is one character from the set drqtpmx, optionally concatenated with one or more of vuaibclo. Afile 
is the archive file. The names are constituent files in the archive file. The meanings of the key charac¬ 
ters are: 

d Delete the named files from the archive file. 

r Replace the named files in the archive file. If the optional character u is used with r, then 
only those files with ‘last-modified* dates later than the archive files are replaced. If an 
optional positicxiing character from the set abi is used, then the posname argument must be 
present and specifies that new files are to be placed after (a) or before (b or i) posname. Oth¬ 
erwise new files are placed at the end. 

q Quickly append the named files to tlw end of the archive file. Optional positioning characters 
are invalid. The command does not check whether the added members are already in the 
archive. Useful only to avoid quadratic behavior when creating a large archive piece-by-piece. 

t Print a table of contents of the archive file. If no names are given, all files in the archive are 
tabled. If names are given, only those files are tabled. 

p Print the named files in the archive. 

m Move the named files to the end of the archive. If a positioning character is present, then the 
posname argument must be present and, as in r, specifies where the files are to be moved. 

X Extract the named files. If no names are given, all files in the archive are extracted. In neither 
case does x alter the archive file. Normally the ‘last-modified’ date of each extracted file is the 
date when it is extracted. However, if o is used, the ‘last-modified’ date is reset to the date 
recorded in the archive. 

v Verbose. Under the verbose option, ar gives a file-by-file description of the making of a new 
archive file from the old archive and the constituent files. When used with t, it gives a long 
listing of all information about the files. When used with p, it precedes each file with a name. 

c Create. Normally ar will create afile when it needs to. The create option suppresses the nor¬ 
mal message that is produced when afile is created. 

1 Local. Normally ar places its temporary files in the directory /tmp. This option causes them 
to be placed in the local directory. 

FILES 

/tmp/v* temporaries 

SEE ALSO 

lorder(l), ld(l), ranlib(l), ar(5), arcv(8) 

BUGS 

If the same file is mentioned twice in an argument list, it may be put in the archive twice. 

The ‘last-modified’ date of a file will not be altered by the o option if the user is not the owner of the 
extracted file, or the super-user. 
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NAME 

ar - archive (library) file format 

SYNOPSIS 

#include <:arJi> 

DESCRIPTION 

The archive ccmunand ar cranbines several files into one. Archives are used mainly as libraries to be 
searched by the link-editor Id. 

A file produced by nr has a magic string at the start, followed by the constituent files, each preceded by 
a file header. Filenames are truncated to IS characters, if necessary. The magic number and header 
layout as described in the include file are: 

/* 

* Copyright (c) 1980 Regents of the University of California. 

* All rights reserved. The Berkeley software License Agreement 

* specifies the tnms and conditicxis for redistribution. 

* 

* @(#)ar.h 5.1 (Berkeley) 5/30/85 

*1 

#defineARMAG "!<arch>\n" 

#define SARMAG 8 

#define ARFMAG "*^n" 

struct ar_hdr ( 

char ar_name[16]; 
char ar_date[12]; 
char ar_uid[6]; 
char ar_gid[6]; 
char ar_mode[8]; 
char ar_sizc[10]; 
char ar_fin[iag[2]; 

); 

The nsune is a blank-padded string. The ar Jmag field contains ARFMAG to help voify the presence 
of a header. The other fields are left-adjusted, blank-padded numbers. They are decimal excejn for 
arjnode^ which is octal. The date is the modification date of the file at the time of its insertion into 
the archive. 

Each file begins on a even (0 mod 2) boundary; a new-line is inserted between files if necessary. 
Nevertheless the size givoi reflects the actual size of the file exclusive of padding. 

Th^ is no provision for empty areas in an archive file. 

The encoding of the header is portable across machines. If an archive contains printable files, the 
archive itself is printable. 

SEE ALSO 

ar(l), ld(l), nm(l) 

BUGS 

File names lose trailing blanks. Most software baling with archives takes even an included blank as a 
name terminator. 
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NAME 

as - VAX-11 assembler 
SYNOPSIS 

as [ -al-16 ] [ [ -dl24 ] [ -L ] [ -W ] [ -V ] [ -J ] [ -R ] [ -t directory ] [ -o objfile ] [ name ... ] 
DESCRIPTION 

As assembles the named files, or the standard input if no file name is specified. The available flags are: 

-a Specifies the alignment of {socedures and data blocks. It is given as a power of two; thus an 
alignment of 3 causes alignment on an eight byte boundary. The default is -a2. 

-d Specifies the number of bytes to be assembled for offsets which involve forward or external 
references, and which have sizes unspecified in the assembly language. The default is -d4. 

-L Save defined labels beginning with a *L*, which are normally discarded to save space in the 
resultant symbol table. The compilers generate such temporary labels. 

-V Use virtual memory for some intermediate storage, rather than a temporary file. 

-W Do not complain about errors. 

-J Use long branches to resolve jumps when byte-displacement branches are insufficient. This 
must be used when a compiler-generated assembly contains branches of more than 32k bytes. 

-R Make initialized data segments read-only, by concatenating them to the text segments. This 
obviates the need to run ^tor scripts on assembly code to make initialized data read-only and 
shared. 

-t Specifies a directory to receive the temporary file, other than the default /tmp. 

All undefined symbols in the assembly are treated as global. 

The ouQ)ut of the assembly is left on the file objfile; if that is omitted, a.out is used. 

EUNICE NOTES 

There are two assemblers provided: lusrleunjvmsas and Ihinjas. See cc{l) or piil) for more informa¬ 
tion. 

FILES 

/tmp/as* default temporary files 

a.out default resultant object file 

SEE ALSO 

ld(l), nm(l), adb(l), dbx(l), a.out(5), vmsas(l) 

Auxiliary documentation Assembler Reference Manual 

AUTHORS 

John F. Reiser 
Robert R. Henry 

BUGS 

-J should be eliminated; the assembler should automatically choose among byte, word and long 
branches. 
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NAME 

at - execute commands at a later time 
SYNOPSIS 

at [ -c ] [ -s ] [ -m ] time [ day ] [ file ] 

DESCRIPTION 

At spools away a copy of the named file to be used as input to sh{\) or csh{l). If the -c flag (for 
(cshiX))) or the -s flag (for (sh(X))) is specified, then that shell will be used to execute the job; if no 
shell is specified, the cunent environment shell is used. If no file name is specified, at prompts for 
commands from standard input until a "D is typed. 

If the -m flag is specified, mail will be sent to the user after the job has been run. If errors occur during 
execution of the job, then a copy of the errOT diagnostics will be sent to the user. If no errors occur, 
then a short message is sent informing the user that no errors occurred. 

The format of the spool file is as follows: A four line header that includes the owner of the job, the 
name of the job, the shell used to run the job, and whether mail will be set after the job is executed. 
The header is followed by a cd command to the current directory and a umask command to set the 
modes on any files created by the job. Then at copies all relevant environment variables to the spool 
file. When the script is run, it uses the user and group ID of the creator of the spool file. 

The time is 1 to 4 digits, with an optional following ‘A’, ‘P’, ‘N’ or ‘M’ for AM, PM, noon or mid¬ 
night. One and two digit numbers are taken to be hours, three and four digits to be hours and minutes. 
If no letters follow the digits, a 24 hour clock time is understood. 

The optional day is either (1) a month name followed by a day number, or (2) a day of the week; if the 
word ‘week’ follows, invocation is moved seven days further off. Names of months and days may be 
recogni 2 ably truncated. Examples of legitimate commands are 

at Sam jan 24 

at -c -m 1530 fr week 

at -s -m 1200n week 

At programs are executed by periodic execution of the command /usr/lib/atrun from cron{%). The 
granularity of at depends upon the how often atrun is executed. 

Error output is lost unless redirected or the -m flag is requested, in which case a copy of the errors is 
sent to the user via mail{\). 

EUNICE NOTES 

The EUNICE BSD at(l) requires write access to the directory lusrispool!at. The file lusriliblatrun can 
also be run periodically by TWG$ADMIN.ATRUN.COM, that is restarted during the EUNICE BSD 
startup procedure. When a EUNICE filename has multiple extensions, the last two extensions cannot be 
composed solely of numbers. Because of this, the filenames of job files were changed to 
lusrlspoollatlyy.ddd. hhhh. *at. 

FILES 


/usr/spool/at 

/usr/spool/at/yy.ddd.hhhh.*at 

/usr/spool/at/past 

/usr/spool/at/lasttimedone 

/usr/lib/atrun 

/etc/eunice/atrun.com 

SEE ALSO 


spooling area 
job file 

directory where jobs are executed from 
last time atrun was run 
executor (run by cron(8)) 
executor of /usr/lib/atrun 


atq(l), atrm(l), calendar(l), sleep(l), cron(8) 
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DIAGNOSTICS 

Complains about various syntax errors and times out of range. 

BUGS 

Due to the granularity of the execution of /usriliblatrun, there may be bugs in scheduling things almost 
exactly 24 hours into the future. 

If the system crashes, mail is not sent to the user informing them that the job was not completed. 

Sometimes old spool files are not removed from the directory fusr/spoollatipast. This is usually due to a 
system crash, and requires that they be removed by hand. 
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NOTE 


NOT PRESENT IN WOLLONGONG’S EUNICE! 


NAME 

atq - print the queue of jobs waiting to be run 
SYNOPSIS 

atq [ -c ] [ -n ] [ name ... ] 

DESCRIPTION 

Atq prints the queue of jobs that are waiting to be run at a later date. These jobs were created with the 
at{\) command. With no flags, the queue is sorted in the order that the jobs will be executed. 

If the -c flag is used, the queue is sorted by the time that the at command was given. 

The -n flag prints only the total number of files that are currently in the queue. 

If a name(s) is provided, only those files belonging to that user(s) are displayed. 

EUNICE NOTES 

Not implemented in EUNICE. 

FILES 

/usr/spool/at spool area 

SEE ALSO 

at(l), atrm(l), cron(8) 
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NOTE 


NOT PRESENT IN WOLLONGONG’S EUNICE! 


NAME 

atrm - remove jobs spooled by at 
SYNOPSIS 

atrm [ -f ] [ -i ] [-] [[ job #] [ name ]... ] 

DESCRIPTION 

Atrm removes jobs that were created with the at(l) command. With the - flag, all jobs belonging to 
the person invoking atrm are removed. If a job number(s) is specified, atrm attempts to remove only 
that job number(s). 

If the -f flag is used, all information regarding the removal of the specified jobs is suppressed. If the -i 
flag is used, atrm asks if a job should be removed; a response of ’y’ causes the job to be removed. 

If a user(s) name is specified, all jobs belonging to that user(s) are removed. This form of invoking 
atrm is useful only to the super-user. 

EUNICE NOTES 

Not implemented in EUNICE. 

FILES 

/usr/spool/at spool area 

SEE ALSO 

at(l), atq(l), cron(8) 
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NAME 

awk - pattern scanning and processing language 
SYNOPSIS 

awk [ -Fc ] [ prog ] [ file ] ... 

DESCRIPTION 

Awk scans each input file for lines that match any of a set of patterns specified in prog. With each pat- 
tOTi in prog there can be an associated action that will be performed when a line of a file matches the 
pattern. The set of patterns may appear literally as prog, or in a file specified as -f file. 

Files are read in order, if there are no files, the standard input is read. The file name means the 
standard input. Each line is matched against the pattern portion of every pattern-action statement; the 
associated action is perfmned fen* each matched pattern. 

An input line is made up of fields separated by white space. (This default can be changed by using FS, 
vide ir^a.) The fields are denoted $1, $2,...; $0 refers to the entire line. 

A pattern-action statement has the form 

pattern { action } 

A missing { action } means print the line; a missing pattern always matches. 

An action is a sequence of statements. A statement can be one of the following: 

if (conditional) statement [ else statement ] 

while (conditional) statement 

for (expression ; conditional; expression ) statement 

break 

continue 

( [ statement ] ... } 

variable = expression 

print [ expression-list ] [ >expression ] 

printf format [, expression-list ] [ >expression ] 

next # skip remaining patterns cm Ais input line 

exit # skip the rest of the input 

Statements are tominated by semicolons, newlines or right braces. An empty expression-list stands for 
the whole line. Expressions take on string or numeric values as appropriate, and are built using the 
operators +, -, *, /, %, and concatenation (indicated by a blank). The C operators ++, —, +=, -=, *=, 
/=, and %=s are also available in expressions. Variables may be scalars, array elements (denoted x[i]) or 
fields. Variables are initialized to the null string. Array subscripts may be any string, not necessarily 
numeric; this allows for a form of associative memory. String constants are quoted 

The print statement prints its arguments on the standard output (or on a file if >file is present), 
separated by the current output field separator, and terminated by the output record separator. The 
printf statement formats its expression list according to the format (see printf{3S)). 

The built-in function length returns the length of its argument taken as a string, or of the whole line if 
no argument. There are also built-in functions exp. log. sqrt, and int. The last truncates its argument 
to an integer. substr(s, m, n) returns the n-character substring of s that begins at position m. The func¬ 
tion sprintfifmt, expr, expr,...) formats the expressions according to the printf(3S) format given by fmt 
and returns the resulting string. 

Patterns are arbitrary Boolean combinations (!, |1, &&, and parentheses) of regular expressions and rela¬ 
tional expressions. Regular expressions must be surrounded by slashes and are as in egrep. Isolated 
regular expressions in a pattern apply to the entire line. Regular expressions may also occur in rela¬ 
tional expressions. 
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A pattern may consist of two patterns separated by a comma; in this case, the action is performed for 
all lines between an occurrence of the first and the next occurrence of the second. 

A relational expression is one of the following: 

expressicHi matchop regular-expression 
expression relop expression 

where a relop is any of the six relational qjerators in C, and a matchop is either ” (for contains) or !” 
(for does not contain). A conditional is an arithmetic expression, a relational expression, or a Boolean 
combination of these. 

The special patterns BEGIN and END may be used to capture control before the first input line is read 
and after the last BEGIN must be the first pattern, END the last. 

A single character c may be used to separate the fields by starting the program with 

BEGIN { FS = "c" } 

or by using the -Fc option. 

Other variable names with special meanings include NF, the number of fields in the current record; NR, 
the ordinal number of the current record; FILENAME, the name of the current input file; OFS, the out¬ 
put field separator (default blank); ORS, the output record separator (default newline); and OFMT, the 
ouQ)ut format for numbers (default "%.6g"). 

EXAMPLES 

Print lines longer than 72 characters: 
length > 72 

Print first two fields in opposite order: 

{ print $2, $1 } 

Add up first column, print sum and average: 

{ s += $1 } 

END { print "sum is”, s," average is", s/NR } 

Print fields in reverse order 

{ for (i = NF; i > 0; —^i) print $i } 

Print all lines between start/stop pairs: 

/start/, /stop/ 

Print all lines whose first field is different from previous one: 

$1 != prev { print; prev = $1 } 

SEE ALSO 

lex(l), sed(l) 

A. V. Aho, B. W. Kemighan, P. J. Weinberger, Awk - a pattern scanning and processing language 

BUGS 

There are no explicit conversions between numbers and strings. To force an expression to be treated as 
a number add 0 to it; to force it to be treated as a string concatenate "" to it. 
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NAME 

basename - strip filename affixes 
SYNOPSIS 

basename string [ suffix ] 

DESCRIPTION 

Basename deletes any prefix ending in 7’ and the if present in string, from string, and prints the 
result on the standard output. It is nc^ally used inside substitution marks ' ' in shell procedures. 

This shell procedure invoked with the argument lusrisrcibinicat.c compiles the named file and moves 
the output to cat in the current directory: 

cc $1 

mv a.out 'basename $1 .c' 

SEE ALSO 

sh(l) 
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NAME 

be - arbitrary-precision arithmetic language 
SYNOPSIS 

be [ -c ] [ -1 ] [ file ... ] 

DESCRIPTION 

Be is an interactive processor for a language which resembles C but provides unlimited precision arith¬ 
metic. It lakes input from any files given, then reads the standard input The -1 argument stands for 
the name of an arbitrary precision math library. The syntax for be programs is as follows; L means 
letter a-z, E means expression, S means statement. 

Comments 

arc enclosed in /♦ and */. 

Names 

simple variables: L 
array elements: L [ E ] 

The words *ibase’, ‘obase’, and ‘scale* 

Other operands 

arbitrarily long numbers with optional sign and decimal point. 

(E) 

sqrt(E) 

length (E ) number of significant decimal digits 
scale (E ) number of digits right of decimal point 
L(E.E) 

Operators 

+ -*/%*(% is remainder;" is power) 

++ — (prefix and postfix; apply to names) 

= <=>=!=:<> 

= ^ *=r /s 

Statements 

E 

{ S ; ...; S } 

if(E)S 

while ( E ) S 

for (E ; E ; E ) S 

null statement 

break 

quit 

Function definitions 

define L ( L ,..., L ) { 
auto L,... , L 
S; ... S 
return (E ) 

) 

Functions in -1 math library 
s(x) sine 

c(x) cosine 

e(x) exponential 

l(x) log 

a(x) arctangent 

j(n,x) Bessel function 
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All functicm arguments are passed by value. 

The value of a statement that is an expression is printed unless the main operator is an assignment. 
Either semicolons or newlines may separate statements. Assignment to scale influences the number of 
digits to be retained on arithmetic operations in the manner of dc{\). Assignments to ibase or obase set 
the input and output number radix respectively. 

The same letter may be used as an array, a fimction, and a simple variable simultaneously. All vari¬ 
ables are global to the program. ‘Auto’ variables are pushed down during function calls. When using 
arrays as function arguments or defining them as automatic variables empty square brackets must follow 
the array name. 

For example 

scale = 20 
define e(x){ 

auto a, b, c, i, s 
a = 1 
b= 1 
s = 1 

for(i=l; ls=l; i++){ 
a ss a*x 
b ss b*i 
c = a/b 

if(c = 0) retuni(s) 
s = s+c 

} 

} 

defines a function to compute an approximate value of the exponential function and 
for(i=l; i<=10; i++) e(i) 

prints approximate values of the exponential function of the first ten integers. 

Be is actually a preprocessor for dc(l), which it invokes automatically, unless the -c (compile only) 
option is present In this case the dc input is sent to the standard output instead. 

FILES 

/usr/lib/lib.b mathematical library 
dc(l) desk calculator prop^ 

SEE ALSO 

dc(l) 

L. L. Cherry and R. Morris, BC - An arbitrary precision desk-calculator language 

BUGS 

No &&, 11, or ! operators. 

For statement must have all three E’s. 

Quit is interpreted when read, not when executed. 
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NAME 

biff - be notified if mail arrives and who it is from 

SYNOPSIS 

biff [ yn ] 

DESCRIPTION 

Bijf informs the system whether you want to be notified when mail arrives during the current terminal 
session. The command 

biff y 

enables notification; the command 
biffn 

disables it When mail notification is enabled, the header and first few lines of the message will be 
printed on your screen whenever mail arrives. A “biff y” command is often included in the file .login 
or .profile to be executed at each login. 

Biff operates asynchronously. For synchronous notification use the MAIL variable of jA( 1) or the mail 
variable of csh{l). 

SEE ALSO 

csh(l), sh(l), mail(l). 
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NAME 

binmail - send or receive mail among users 
SYNOPSIS 

/bin/mail [ + ] [ -i ] [ person ] ... 

/bin/maU [ + ] [ -i ] -f file 

DESCRIPTION 

Note: This is the old version 7 UNIX system mail program. The default mail command is described in 
and its binary is in the directwy lusriucb. 

mail with no argument prints a user’s mail, message-by-message, in last-in, first-out order, the optional 
argument + displays the mail messages in first-in, &st-out order. For each message, it reads a line from 
the standard input to direct disposition of the message. 

newline Go on to next message, 
d Delete message and go on to the next 
p Print message again. 

Go back to previous message, 
s [file ] ... 

Save the message in the named files (‘mbox* default), 
w [file ] ... 

Save the message, without a header, in the named files (‘mbox’ default), 
m [ person ] ... 

Mail the message to the named persons (yourself is default). 

EOT (control-D) 

Put unexamined mail back in the mailbox and stop, 
q Same as EOT. 

\ command 

Escape to the Shell to do command, 

* Print a command summary. 

An interrupt normally terminates the mail command; the mail file is unchanged. The optional argument 
-i tells mail to continue after interrupts. 

When persons are named, mail takes the standard input up to an end-of-file (or a line with just ‘.’) and 
adds it to each person’s ‘mail’ file. The message is preceded by the sender’s name and a postmark. 
Lines that look like postmarks are prepended with *>’. A person is usually a user name recognized by 
loginiX). To denote a recipient on a remote system, prefix person by the system name and exclamation 
mark (see Mucp(lQ). 

The -f option causes the named file, for example, ‘mbox’, to be printed as if it were the mail file. 

When a user logs in he is informed of the presence of mail. 

FILES 

/etc/passwd to identify sender and locate persons 

/usr/spool/mail/* incoming mail for user ♦ 

mbox saved mail 

/tmp/ma* temp file 

/usr/spool/mail/*.lock lock for mail directory 
dead.letter unmailable text 
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SEE ALSO 

Mail(l), write(l). uucp(lC), uux(lC), xsend(l), sendmail(8) 

BUGS 

Race conditions sometimes result in a failure to remove a lock file. 

Normally anybody can read your mail, unless it is sent by xsend{\). An installation can overcome this 
by making mail a set-user-id command that owns the mail directory. 
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NAME 

cal - print calendar 

SYNOPSIS 

cal [ month ] year 

DESCRIPTION 

Cal prints a calendar for die specified year. If a month is also specified, a calendar just for that month 
is printed. Year can be between 1 and 9999. The month is a number between 1 and 12. The calendar 
produced is that for England and her colonies. 

Try September 1752. 

BUGS 

The year is always considered to start in January even though this is historically naive. 

Beware that ‘cal 78’ refers to the early Christian era, not the 20th century. 
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NAME 

calendar - reminder service 

SYNOPSIS 

calendar [ - ] 

DESCRIPTION 

Calendar consults the file ‘calendar’ in the current directory and prints out lines that contain today’s or 
tomorrow’s date anywhere in the line. Most reasonable month-day dates such as ‘Dec. 7,’ ‘december 
7,’ ‘12/7,’ etc., are recognized, but not ‘7 December’ or ‘7/12’. If you give the month as with a 
date, i.e. “♦ 1”, that day in any month will do. On weekends ‘tomorrow’ extends through Monday. 

When an argument is present, calendar does its job for every user who has a file ‘calendar’ in his login 
directory and sends him any positive results by mail(l). Normally this is done daily in the wee hours 
under control of cron(S). 

The file ‘calendar’ is first run through the “C” preprocessor, Ilibfcpp, to include any other calendar 
files specified with the usual “#include” syntax. Included calendars will usually be shared by all users, 
maintained and documented by the local administration. 

FILES 

calendar 

/usr/lib/calendar to figure out today’s and tomorrow’s dates 

/etc/passwd 

/tmp/cal* 

/lib/cpp, egrep, sed, mail as subprocesses 
SEE ALSO 

at(l), cron(8), mail(l) 

BUGS 

Calendar's extended idea of ‘tomorrow’ doesn’t account for holidays. 
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NAME 

cat - catenate and print 
SYNOPSIS 

cat [ -u ] [ -n ] [ -s ] [ -V ] file ... 

DESCRIPTION 

Cat reads each file in sequence and displays it on the standard output. Thus 
cat file 

displays the file on the standard output, and 
cat filel file2 >file3 

concatenates the first two files and places the result on the third. 

If no input file is given, or if the argument is encountered, cat reads from the standard input file. 
Output is buffered in the block size recommended by statO) unless the standard output is a terminal, 
when it is line buffered. The -u option makes the output completely unbuffered. 

The -n option displays the output lines preceded by lines numbers, numbered sequentially from 1. 
Specifying the ~b option with the -n option omits the line numbers from blank lines. 

The -s option crushes out multiple adjacent empty lines so that the ouq)ut is displayed single spaced. 

The -V option displays non-printing charact^s so that they are visible. Control characters print like "X 
for control-x; the delete character (octal 0177) prints as "?. Non-ascii characters (with the high bit set) 
are printed as M- (for meta) followed by the character of the low 7 bits. A -e option may be given 
with the -V option, which displays a ‘$’ character at the end of each line. Specifying the -t option with 
the -V option displays tab characters as "I. 

SEE ALSO 

cp(l), ex(l), more(l), pr(l), tail(l) 

BUGS 

Beware of ‘cat a b >a’ and ‘cat a b >b’, which destroy the input files before reading them. 
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NAME 

cb - C program beautifier 

SYNOPSIS 

cb 

DESCRIPTION 

Cb places a copy of the C program from the standard input on the standard output with spacing and 
indentation that displays the structure of the program. 
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NAME 

cc - C compiler 
SYNOPSIS 

cc [ option ] ... file ... 

DESCRIPTION 

Cc is the UNIX C compiler. Cc accepts several types of arguments: 

Arguments whose names end with ‘.c’ are taken to be C source programs; they are compiled, and each 
object program is left on the file whose name is that of the source with ‘.o’ substituted for ‘.c’. The 
‘.o’ file is normally deleted, however, if a single C program is compiled and loaded all at one go. 

In the same way, arguments whose names end with ‘.s’ are taken to be assembly source programs and 
are assembled, producing a ‘.o’ file. 

The following options are interpreted by cc. See ld(l) for load-time q)tions. 

-c Suppress the loading phase of the compilation, and force an object file to be produced even if 
(Mily one program is compiled. 

-g Have the compiler produce additional symbol table information for dbx(\). Also pass the -Ig 
flag to ld(l). 

-go Have the compiler produce additional symbol table information for the obsolete debugger 
sdb(l). Also pass the -4g flag to ld(l). 

-w Suppress warning diagnostics. 

-p Arrange for the compiler to produce code which counts the number of times each routine is 
called. If loading takes place, replace the standard startup routine by one which automatically 
calls monitorQ) at the start and arranges to write out a mon.out file at normal termination of 
execution of the object program. An execution profile can then be generated by use of 
profil). 

-pg Causes the compiler to produce counting code in the manner of -p, but invokes a run-time 
recording mechanism that keeps more extensive statistics and produces a gmon.out file at nor¬ 
mal termination. Also, a profiling library is searched, in lieu of the standard C library. An 
execution profile can then be generated by use of gprof(l). 

-O Invoke an object-code improver. 

-R Passed on to as, making initialized variables shared and read-only. 

-S Compile the named C programs, and leave the assembler-language output on corresponding 

files suffixed ‘.s’. 

-M Run only the macro preprocessor on the named C programs, requesting it to generate Makefile 
dependencies and send toe result to toe standard output. 

-E Run only toe macro preprocessor on toe named C programs, and send toe result to toe stan¬ 
dard output 

-C prevent toe macro preprocessor from eliding comments. 

-o output 

Name toe final output file output. If this option is used toe file ‘a.out’ will be left undis¬ 
turbed. 

-Dftame=def 

-Dname Define toe name to the preprocessor, as if by ‘#define’. If no definition is given, the name is 
defined as "1". 
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-Vname Remove any initial definition of name. 

-Jdir ‘#include’ files whose names do not begin with 7’ are always sought first in the directory of 
the file argument, then in directories named in -I options, then in directories on a standard 
list. 

-l^ir Library archives are sought first in directories named in -L options, then in directories on a 
standard list 

-f Use an alternate compiler which does not convert expressions involving only floats to double. 
This does not conform to the standard which states that all intermediate results should be con- 
voted to double but does provide a speed improvement for programs which don’t require full 
double precision. This option also makes register float variables work appropriately. 

-^string Find substitute compiler passes in the files named string with the suffixes cpp, ccom and c2. 
If string is empty, use a standard b^ki^ version. 

-t[p012] Find only the designated compiler passes in the files whose names are constructed by a -B 
option. In the absence of a -B option, the string is taken to be 7usr/c/’. 

Other arguments are taken to be either loader option arguments, or C-compatible object programs, typi¬ 
cally produced by an earlier cc run, or perhaps libraries of C-compatible routines. These programs, 
together with the results of any compilations specified, are loaded (in the order given) to produce an 
executable program with name a.out 

EUNICE NOTES 

cc(l) has been modified to create either VMS ot UNIX objects. It will read the value of the csh vari¬ 
able, AS_IMAGE, to determine if the UNIX or VMS assembler should be used. The value of 
LD.Ih^GE will determine whether the UNIX or VMS loader should be used as the loader. Add the 
following lines to a .cshrc in your home directory. 


# Have cc(l) or f77(l) use UNIX assembler and loader, 
alias unixobj ’unsetenv AS_IMAGE; unsetenv LD_IMAGE’ 

# 

# Have cc(l) or f77(l) use VMS assembler and loader. 

alias vmsobj ’setenv AS.IMAGE /usr/eun/vmsas; setenv LD_IMAGE /usr/eun/vmsld’ 
Also add either of the following lines, depending on your choice of object type. 


unixobj 

vmsobj 


FILES 


The -g flag for additional symbol table information can only be used with UNIX objects. 
Note: See ld(l) for additional flags (-noshare, -nopObufs, -notraceback) 


file.c 

file.o 

a.out 

/tmp/ctm? 

/lib/cpp 

/lib/ccom 

/Ub/sccom 

/usr/c/occom 

/usr/c/ocpp 


input file 
object file 
loaded output 
temporary 
preprocessor 
compiler 

compiler for single precision floats 
backup compiler 
backup preprocessor 
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/lib/c2 optional optimizer 

/lib/crtO.o runtime startoff 

/lib/mcrtO.o startoff for profiling 

/usr/lib/gcrtO.ostartoff for gprof-profiling 
/lib/libc.a standard library, see intro(3) 

/usr/lib/libc_p.aprofiling library, see intro {3) 

/usr/include standard directory for ‘#include’ files 
mon.out file produced for analysis by prof{l) 

gmon.out file produced for analysis by gprofO) 

SEE ALSO 

B. W. Kemighan and D. M. Ritchie, The C Programming Language, Prentice-Hall, 1978 
B. W. Kemighan, Programming in C—a tutorial 
D. M. Ritchie, C Reference Manual 

monitor(3), prof(l), gprof(l), adb(l), ld(l), dbx(l), as(l), vmsas(lW), vmsld(lW) 

DIAGNOSTICS 

The diagnostics produced by C itself are intended to be self-explanatory. Occasional messages may be 
produced by the assembler or loader. 

BUGS 

The compiler currently ignores advice to put char, unsigned char, short, unsigned short, float, or 
double variables in registers, except as noted above. It previously produced poor, and in some cases 
incorrect, code for such declarations. 
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NAME 

cd - change working directory 

SYNOPSIS 

cd directory 

DESCRIPTION 

Directory becomes the new working directory. The process must have execute (search) permission in 
directory. 

Because a new process is created to execute each command, cd would be ineffective if it were written 
as a normal command. It is therefore recognized and executed by the shells. In csh(l) you may 
specify a list of directories in which directory is to be sought as a subdirectory if it is not a subdirec¬ 
tory of the current directory; see the description of the cdpath variable in cshil). 

SEE ALSO 

csh(l), sh(l), pwd(l), chdir(2) 
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NAME 

checknr - check nroff/troff files 
SYNOPSIS 

checknr [ -s ] [ -f ] [ -a.xl.yl.x2.y2.xn.yn ] [ -c.xl.x2.x3 ... .xn ] [file ... ] 

DESCRIPTION 

Checknr checks a list of nroff{\) or trojf{\) input files for certain kinds of errors involving mismatched 
opening and closing delimiters and unknown commands. If no files are specified, checknr checks the 
standard input Delimeters checked are: 

(1) Font changes using \fx ... \fP. 

(2) Size changes using \sx ... NsO. 

(3) Macros that come in open ... close forms, for example, the .TS and .TE macros which must 
always come in pairs. 

Checknr knows about the ms(J) and me(7) maox) packages. 

Additional pairs of macros can be added to the list using the -a option. This must be followed by 
groups of six characters, each group defining a pair of macros. The six characters are a period, the first 
macro name, another period, and the second macro name. For example, to define a pair .BS and .ES, 
use -a.BS.ES 

The -c option defines commands which would otherwise be complained about as undefined. 

The -f option requests checknr to ignore \f fwit changes. 

The -s option requests checknr to ignore Ns size changes. 

Checknr is intended to be used on documents that are prepared with checknr in mind, much the same as 
liru. It expects a certain document writing style for \f and Ns commands, in that each Nfx must be ter¬ 
minated with NfP and each Nsx must be terminated with NsO. While it will work to directly go into the 
next font or explicitly specify the original font or point size, and many existing documents actually do 
this, such a practice will produce complaints from checknr. Since it is probably better to use the NfP and 
NsO forms anyway, you should think of this as a contribution to your document preparation style. 

SEE ALSO 

nroff(l), troff(l), checkeq(l), ms(7), me(7) 

DIAGNOSTICS 

Complaints about unmatched delimiters. 

Complaints about unrecognized commands. 

Various complaints about the syntax of commands. 

BUGS 

There is no way to define a 1 character macro name using -a. 

Does not correctly recognize certain reasonable constructs, such as conditionals. 
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NOTE 


NOT PRESENT IN WOLLONGONG’S EUNICE! 


NAME 

chfn, chsh, passwd - change password file information 
SYNOPSIS 

passwd [ -f ] [ -s ] [ name ] 

DESCRIPTION 

This command changes (or installs) a password, login shell (-s option), or GECOS information field (-f 
option) associated with the user name (your own name by default). 

When altering a password, the program prompts for the current password and then for the new one. 
The caller must supply both. The new password must be typed twice to forestall mistakes. 

New passwords must be at least four characters long if they use a sufficiently rich alphabet and at least 
six characters long if monocase. These rules are relaxed if you are insistent enough. 

Only the owner of the name or the super-user may change a password; the owner must prove he knows 
the old password. 

When altering a login shell, passwd displays the current login shell and then prompts for the new one. 
The new login shell must be one of the approved shells listed in letcishells unless you are the super- 
user. If letcishells does not exist, the only shells that may be specified are Ibinish and Ibinicsh. 

The super-user may change anyone’s login shell; normal users may only change their own login shell. 

When altering the GECOS information field, passwd displays the current information, broken into fields, 
^ interpreted by the finger{\) program, among others, and prompts for new values. These fields 
include a user’s “real life’’ name, office room number, office phone number, and home phone number. 
Included in each prompt is a default value, which is enclosed between brackets. The default value is 
accepted simply by typing a carriage return. To enter a blank field, the word “none” may be typed. 
Below is a sample run: 

Name [Biff Studsworth H]: 

Room number (Exs; 597E or 197C) []: 521E 

Office Phone (Ex; 1632) []; 1863 

Home Phone (Ex; 987532) [5771546]; none 

Passwd allows phone numbers to be entered with or without hyphens. It is a good idea to run finger 
after changing the GECOS information to make sure everything is setup properly. 

The super-user may change anyone’s GECOS information; normal users may only change their own. 
EUNICE NOTES 

All password authentication is done by VMS and not EUNICE. Running the command will not change 
the letcipassword file, but will change the VMS password instead. 

The commands chfh and chsh are not implemented in EUNICE. 

FILES 

/etc/passwd The file containing all of this information 
/etc/shells The list of approved shells 

SEE ALSO 

login(l), finger(l), passwd(5), crypt(3) 

Robert Morris and Ken Thompson, UNIX password security 
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NOTE 


NOT PRESENT IN WOLLONGONG’S EUNICE! 


NAME 

chgrp - change group 
SYNOPSIS 

chgrp [ -f -R ] group file ... 

DESCRIPTION 

Chgrp changes the group-ID of the files to group. The group may be either a decimal GID or a group 
name found in the group-ID file. 

The user invoking chgrp must belong to the specified group and be the owner of the file, or be the 
super-user. 

No errors are reported when the -f (force) option is given. 

When the -R option is given, chgrp recursively descends its directory arguments setting the specified 
group-ID. When symbolic links are encountered, their group is changed, but they are not traversed. 

EUNICE NOTES 

Not implemented in EUNICE. 

FILES 

/etc/group 
SEE ALSO 

chown(2), passwd(5), group(5) 
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NAME 

chmod - change mode 
SYNOPSIS 

chmod [ -Rf ] mode file ... 

DESCRIPTION 

The mode of each named file is changed accm'ding to mode, which may be absolute or symbolic. An 
absolute mode is an octal number constructed from the OR of the following modes: 

4000 set usCT ID on executicxi 
2000 set group ID on execution 

1000 sticky bit, see chmod{2) 

0400 read by owner 

0200 write by owner 

0100 execute (search in directory) by owner 

0070 read, write, execute (search) by group 

0007 read, write, execute (search) by others 

A symbolic mode has the form: 

[who] op permission [op permission] ... 

The who part is a combination of the letters u (for user’s permissions), g (group) and o (other). The 
letter a stands for all, or ugo. If who is omitted, the default is a but the setting of the file creation 
mask (see umask(2)) is taken into account 

Op can be + to add permission to the file’s mode, - to take away permission and = to assign permission 
absolutely (all other bits will be reset). 

Permission is any combination of the letters r (read), w (write), x (execute), X (set execute only if file 
is a directory or some other execute bit is set), s (set owner or group id) and t (save text - sticky). 
Letters u, g, or o indicate that permission is to be taken from the current mode. Omitting permission is 
only useful with = to take away all permissions. 

When the -R option is given, chmod recursively descends its directory arguments setting the mode for 
each file as described above. When symbolic links are encountered, their mode is not changed and they 
are not traversed. 

If the -f option is given, chmod will not complain if it fails to change the mode on a file. 

EXAMPLES 

The first example denies write permission to others, the second makes a file executable by all if it is 
executable by anyone: 

chmod o-w file 
chmod +X file 

Multiple symbolic modes separated by commas may be given. Operations are performed in the order 
specified. The letter s is only useful with u or g. 

Only the owner of a file (or the super-user) may change its mode. 

EUNICE NOTES 

Files and directories under EUNICE adhere to the UNIX file protection conventions. In order to imple¬ 
ment UNIX-like file protections using the VMS file protection mechanism, the VMS "DELETE" per¬ 
mission is enabled. This does not mean that file security has been violated. 

In order to delete a file, VMS (like UNIX) requires that the directory in which the file resides have 
"WRITE" permission to the person attempting the deletion. In addition, the file in question must have 
"DELETE" turned on. 


April 18, 1989 


The Wollongong Group 


1 



CHMOD(l) 


UNIX Programmer’s Manual 


CHMOD(l) 


Under UNIX, if the directory has "WRITE" permission turned on, then anybody can delete any file in 
that directory. If the file also has "WRITE" permission, the file is deleted immediately. If it does not, 
then UNIX will ask whether the file really is to be removed, and will allow it if the answer is 
affirmative. The documentation for rm(l) in the UNIX Programmer’s Manual discusses UNIX 
"WRITE" permission. Files and directories created under EUNICE will be created with the VMS pro¬ 
tections necessary for rm to work. 

The COMBINATION of the directory and the file protections determine whether a file may be deleted. 
The EUNICE command chmod automatically adds the VMS "DELETE" command in order to remain 
consistent with the UNIX conventions - that the "WRITE" permission on directory decide the access to 
the files inside it. 

As may be seen, in both VMS and UNIX the directory permission are the critical item. Good file 
management dictates that the directories wherein important files reside be set with protections appropri¬ 
ate to the occasion. As long as the directories are correctly set, nobody will be able to delete any file 
for which they lack proper authorization. 

SEE ALSO 

ls(l), chmod(2), stat(2), umask(2), chown(8) 
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NOTE 


NOT PRESENT IN WOLLONGONG’S EUNICE! 


NAME 

chfn, chsh, passwd - change password file information 
SYNOPSIS 

passwd [ -f ] [ -s ] [ name ] 

DESCRIPTION 

This command changes (or installs) a password, login shell (-s option), or GECOS information field (-f 
option) associated with the user name (your own name by default). 

When altering a password, the program prompts for the current password and then for the new one. 
The caller must supply both. The new password must be typed twice to forestall mistakes. 

New passwords must be at least four characters long if they use a sufficiently rich alphabet and at least 
six characters long if monocase. These rules are relaxed if you are insistent enough. 

Only the owner of the name or the super-user may change a password; the owner must prove he knows 
the old password. 

When altering a login shell, passwd displays the current login shell and then prompts for the new one. 
The new login shell must be one of the approved shells listed in letc/shells unless you are the super- 
user. If letclshells does not exist, the only shells that may be specified are Ibinish and /bin/csh. 

The super-user may change anyone’s login shell; normal users may only change their own login shell. 

When altering the GECOS information field, passwd displays the current information, broken into fields, 
as interpreted by the finger{\) program, among others, and prompts for new values. These fields 
inclu^ a user’s “real life’’ name, office room number, office phone numb^, and home phone number. 
Included in each prompt is a default value, which is enclosed between brackets. The default value is 
accepted simply by typing a carriage return. To enter a blank field, the word “none” may be typed. 
Below is a sample run: 

Name [BUT Studsworth n]: 

Room number (Exs: 597E or 197C) []: 521E 

Office Phone (Ex: 1632) []: 1863 

Home Phone (Ex: 987532) [5771546]; none 

Passwd allows phone numbers to be entered with or without hyphens. It is a good idea to run finger 
after changing the GECOS information to make sure everything is setup properly. 

The super-user may change anyone’s GECOS information; normal users may only change their own, 
EUNICE NOTES 

All password authentication is done by VMS and not EUNICE. Running the command will not change 
the letcipassword file, but wiU change the VMS password instead. 

The commands cirfn and chsh are not implemented in EUNICE. 

FILES 

/etc/passwd The file containing all of this information 
/etc/shells The list of approved shells 

SEE ALSO 

login(l), finger(l), passwd(5), crypt(3) 

Robert Morris and Ken Thompson, UNIX password security 
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NAME 

ci - check in RCS revisions 

SYNOPSIS 

ci [ options ] file ... 

DESCRIPTION 

Ci stores new revisions into RCS files. Each file name ending in ‘,v’ is taken to be an RCS file, all 
others are assumed to be working files containing new revisions. Ci deposits the contents of each work¬ 
ing file into the cOTresponding RCS file. 

Pairs of RCS files and working files may be specified in 3 ways (see also the example section of co 

(D). 

1) Both the RCS file and the working file are given. The RCS file name is of the form pathl/workfile,v 
and the working file name is of the form patkZ/workfile, where pathll and path2/ are (possibly different 
or empty) paths and workfile is a file name. 

2) Only the RCS file is given. Then the working file is assumed to be in the current directory and its 
name is derived from the name of the RCS file by removing pathlj and the suffix ‘,v’. 

3) Only the working file is given. Then the name of the RCS file is derived fi-om the name of the work¬ 
ing file by removing pathll and s^pending the suffix ‘,v’. 

If the RCS file is omitted or specified without a path, then ci looks for the RCS file first in the directory 
./RCS and then in the current directory. 

For ci to work, the caller’s login must be on the access list, except if the access list is empty or the 
caller is the superuser or the owner of the file. To append a new revision to an existing branch, the tip 
revision on that branch must be locked by the caller. Otherwise, only a new branch can be created. This 
restriction is not enforced for the owner of the file, unless locking is set to strict (see res (1)). A lock 
held by someone else may be broken with the res command. 

Normally, ci checks whether the revision to be deposited is different from the preceding one. If it is not 
different, ci either aborts the deposit (if -q is given) or asks whether to abort (if -q is omitted). A depo¬ 
sit can be forced with the -f option. 

For each revision deposited, ci prompts for a log message. The log message should summarize the 
change and must be terminated with a line containing a single If several files are checked in, ci 
asks whether to reuse the previous log message. If the std. input is not a terminal, ci suppresses the 
prompt and uses the same log message fw all files. See also -m. 

The number of the deposited revision can be given by any of the options -r, -f, -k, -1, -u, or -q (see -r). 

If the RCS file does not exist, ci creates it and deposits the contents of the working file as the initial 
revision (default number: 1.1). The access list is initialized to empty. Instead of the log message, ci 
requests descriptive text (see -t below). 

-r[rev] assigns the revision number rev to the checked-in revision, releases the corresponding lock, 
and deletes the working file. This is also the default 

If rev is omitted, ci derives the new revision number from the caller’s last lock. If the caller 
has locked the tip revision of a branch, the new revision is appended to that branch. The 
new revision number is obtained by incrementing the tip revision number. If the caller 
locked a non-tip revision, a new branch is started at that revision by incrementing the 
highest branch number at that revision. The default initial branch and level numbers are 1. 
If the caller holds no lock, but he is the owner of the file and locking is not set to strict, 
then the revision is appended to the trunk. 

If rev indicates a revision number, it must be higher than the latest one on the branch to 
which rev belongs, or must start a new branch. 
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If rev indicates a branch instead of a revision, the new revision is appended to that branch. 
The level number is obtained by incrementing the tip revision number of that branch. If 
rev indicates a non-existing branch, that branch is created with the initial revision numbered 
rev.l. 


Exception: On the trunk, revisions can be appended to the end, but not inserted. 

-f[rev] forces a deposit; the new revision is deposited even it is not different from the preceding 
one. 

-k[rev] searches the working file for keyword values to determine its revision number, creation 
date, audior, and state (see co (1)), and assigns these values to the deposited revision, rather 
than computing them locally. A revision number given by a command option overrides the 
number in the working file. This option is useful for software distribution. A revision that 
is sent to several sites should be checked in with the -k option at these sites to preserve its 
original number, date, author, and state. 

~l[rev] works like -r, except it performs an additional co -I for the deposited revision. Thus, the 
deposited revision is immediately checked out again and locked. This is useful for saving a 
revision although one wants to continue editing it after the checkin. 

-u[rev] works like -1, except that the deposited revision is not locked. This is useful if one wants 
to process (e.g., compile) the revision immediately after checkin. 

-q[rev] quiet mode; diagnostic output is not printed. A revision that is not different from the 
preceding one is not deposited, unless -f is given. 

-mmsg uses the string msg as the log message for all revisions checked in. 

-nname assigns the symbolic name name to the number of the checked-in revision. Ci prints an 
error message if name is already assigned to another number. 

-Nname same as -n, except that it overrides a previous assignment of name. 

-estate sets the state of the checked-in revision to the identifier state. The default is Exp. 

-t[£x(/i/e] writes descriptive text into the RCS file (deletes the existing text). If txtfile is omitted, ci 
prompts the user for text supplied from the std. input, terminated with a line containing a 
single Otherwise, the descriptive text is copied from the file txtfile. During initializa¬ 
tion, descriptive text is requested even if -t is not given. The prompt is suppressed if std. 
input is not a terminal. 

DIAGNOSTICS 

For each revision, ci prints the RCS file, tte working file, and the number of both the deposited and the 
preceding revision. The exit status always refers to the last file checked in, and is 0 if the operation 
was successful, 1 otherwise. 

FILE MODES 

An RCS file created by ci inherits the read and execute permissions from the working file. If the RCS 
file exists already, ci preserves its read and execute permissions. Ci always turns off all write permis¬ 
sions of RCS files. 


FILES 

The caller of the command must have read/write permission for the directories containing the RCS file 
and the working file, and read permission for the RCS file itself. A number of temporary files are 
created. A semaphore file is created in the directory containing the RCS file. Ci always creates a new 
RCS file and unlinks the old one. This strategy makes links to RCS files useless. 

IDENTIFICATION 

Author: Walter F. Tichy, Purdue University, West Lafayette, IN, 47907. 

Revision Number: 3.1 ; Release Date: 83/04/04 . 
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Copyright © 1982 by Walter F. Tichy. 

SEE ALSO 

CO (1), ident(l), res (1), resdiff (1), resmerge (1), rlog (1), resfile (5). 

Walter F. Tichy, "Design, Implementation, and Evaluation of a Revision Control System," in Proceed¬ 
ings of the 6th International Conference on Software Engineering, IEEE, Tokyo, SepL 1982. 

BUGS 
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NAME 

clear - clear terminal screen 

SYNOPSIS 

clear 

DESCRIPTION 

Clear clears your screen if this is possible. It looks in the environment for the terminal type and tiien 
in letcitermcap to figure out how to clear the screen. 

FILES 

/etc/termcap terminal capability data base 
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NAME 

cmp - compare two files 
SYNOPSIS 

cmp [ -1 ] [ -s ] filel file2 
DESCRIPTION 

The two files are compared. (If filel is the standard input is used.) Under default options, cmp 
makes no comment if the files are the same; if they differ, it announces the byte and line number at 
which the difference occurred. If one file is an initial subsequence of the other, Aat fact is noted. 

Options: 

-1 Print the byte number (decimal) and the differing bytes (octal) for each difference. 

-s Print nothing for differing files; return codes only. 

SEE ALSO 

diff(l), comm(l) 

DIAGNOSTICS 

Exit code 0 is returned for identical files, 1 for different files, and 2 for an inaccessible or missing argu¬ 
ment 
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NAME 

CO - check out RCS revisions 

SYNOPSIS 

CO [ options ] file ... 

DESCRIPTION 

Co retrieves revisions from RCS files. Each file name ending in ‘,v’ is taken to be an RCS file. All 
other files are assumed to be working files. Co retrieves a revision from each RCS file and stores it 
into the corresponding working file. 

Pairs of RCS files and working files may be specified in 3 ways (see also the example section). 

1) Both the RCS file and the working file are given. The RCS file name is of the form pathl/workfile,\ 
and the working file name is of the form pathllworkfile, where pathlf and patKlI are (possibly different 
or empty) paths and worl^le is a file name. 

2) Only the RCS file is given. Then the working file is created in the current directory and its name is 
derived firom the name of the RCS file by removing pathl/ and the suffix ‘,v’. 

3) Only the working file is given. Then the name of the RCS file is derived from the name of the 
working file by removing path2l and appending the suffix ‘,v’. 

If the RCS file is omitted or specified without a path, then co looks for the RCS file first in the direc¬ 
tory ./RCS and then in the current directOTy. 

Revisions of an RCS file may be checked out locked or unlocked. Locking a revision prevents overlap¬ 
ping updates. A revision checked out for reading or processing (e.g., compiling) need not be locked. A 
revision checked out for editing and later checkin must normally be locked. Locking a revision 
currently locked by another user fails. (A lock may be broken with the res (1) command.) Co with lock¬ 
ing requires the caller to be on the access list of the RCS file, unless he is the owner of the file or the 
superuser, or the access list is empty. Co without locking is not subject to accesslist restrictions. 

A revision is selected by number, checkin date/time, author, or state. If none of these options are 
specified, the latest revision on the trunk is retrieved. When the options are applied in combination, the 
latest revision that satisfies all of them is retrieved. The options for date/time, author, and state retrieve 
a revision on the selected branch. The selected branch is either derived from the revision number (if 
given), or is the highest branch on the trunk. A revision number may be attached to one of the options 
-I -P, -q, or -r. 

A CO command applied to an RCS file with no revisions creates a zero-length file. Co always performs 
keyword substitution (see below). 

•A[rev] locks the checked out revision for the caller. If omitted, the checked out revision is not 
locked. See option -r for handling of the revision number rev. 

-p[rev] prints the retrieved revision on the std. output rather than storing it in the working file. 
This option is useful when co is part of a pipe. 

-q[rev] quiet mode; diagnostics are not printed. 

-ddate retrieves the latest revision on the selected branch whose checkin date/time is less than or 
equal to date. The date and time may be given in free format and are converted to local 
time. Examples of formats for date: 

22-April-1982,17:20-CDT, 

2:25 AM, Dec. 29.1983, 

Tue-PDT, 1981, 4pm Jul 21 (free format), 

Fri, April 16 15:52:25 EST 1982 (output of ctime). 

Most fields in the dale and time may be defaulted. Co determines the defaults in the order 
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year, month, day, hour, minute, and second (most to least significant). At least one of 
these fields must be provided. For omitted fields that are of higher significance than the 

highest provided fieli the current values are assumed. For all other omitted fields, the 

lowest possible values are assumed. For example, the date "20, 10:30” defaults to 
10:30:00 of the 20th of the current month and current year. The date/time must be quoted 
if it contains spaces. 

-T[rev] retrieves the latest revisitMi whose number is less than or equal to rev. If rev indicates a 
branch rather than a revision, the latest revision on that branch is retrieved. Rev is com¬ 
posed of one or more numeric or symbolic fields separated by The numeric equivalent 
of a symbolic field is specified with the -n option of the commands ci and res. 

-estate retrieves the latest revision on the selected branch whose state is set to state. 

-w[login] retrieves the latest revision on the selected branch which was checked in by the user with 

login name login. If the argument login is omitted, the caller’s login is assumed. 

-ijoinlist generates a new revision which is the join of the revisions on joinlist. Joinlist is a 
comma-separated list of pairs of the form rev2:rev3, where rev2 and rev3 are (symbolic or 
numeric) revision numbers. For the initial such pair, revl denotes the revision selected by 
the opticHis -1,..., -w. For all oUict pairs, revl denotes the revision generated by the previ¬ 
ous pair. (Thus, the ouq)ut of one join becomes the input to the next) 

For each pair, co joins revisions revl and rev3 with respect to rev2. This means that all 
changes that transform rev2 into revl are applied to a copy of rev3. This is particularly 
useful if revl and rev3 are the ends of two baches that have rev2 as a common ancestor. 
If revl < rev2 < rev3 on the same branch, joining generates a new revision which is like 
rev3, but with all changes that lead from revl to rev2 undone. If changes from rev2 to 
revl overlap with changes from rev2 to rev3, co prints a warning and includes the over- 
l^ping sections, delimited by the lines «««< revl, asss=a:s:==, and »»»> rev3. 


For the initial pair, rev2 may be omitted. The default is the common ancestor. If any of 
the arguments indicate branches, the latest revisions on those branches are assumed. If the 
option -1 is present, the initial revl is locked. 

KEYWORD SUBSTITUnON 

Strings of the form $keyword$ and $keyword:...$ embedded in the text are replaced with strings of the 
form $keyword: value $, where keyword and value are pairs listed below. Keywords may be embedded 
in literal strings or comments to identify a revision. 

Initially, the user enters strings of the form $keyword$. On checkout, co replaces these strings with 
strings of the form $keyword: value $. If a revision containing strings of the latter form is checked back 
in, the value fields will be replaced during the next checkout Thus, the keyword values are automati¬ 
cally updated on checkout 

Keywords and their corresponding values: 

$Author$ The login name of the user who checked in the revision. 

$Date$ The date and time the revision was checked in. 

$Header$ A standard header containing the RCS file name, the revision number, the date, the 

author, and the state. 


$Locker$ 

$Log$ 



The login name of the user who locked the revision (empty if not locked). 

The log message supplied during checkin, preceded by a header containing the RCS file 
name, the revision number, the author, and the date. Existing log messages are NOT 
replaced. Instead, the new log message is inserted after $Log:...$. This is useful for 
accumulating a complete change log in a source file. 
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$Revision$ The revision number assigned to the revision. 

$Source$ The full pathname of the RCS file. 

$State$ The state assigned to the revision with res -s or ci -s. 

DIAGNOSTICS 

The RCS file name, the working file name, and the revision number retrieved are written to the diag¬ 
nostic output. The exit status always refers to the last file checked out, and is 0 if the operation was 
successful, 1 otho^ise. 

EXAMPLES 

Suppose the current directory contains a subdirectory ‘RCS’ with an RCS file ‘io.c,v’. Then all of the 
following commands retrieve the latest revision fitom ‘RCS^o.c,v’ and store it into ‘io.c’. 

CO io.c; CO RCSAo.c,v; co io.c,v; 

CO io.c RCSAo.c,v; co io.c io.c,v; 

CO RCS/io.c,v io.c; co io.c,v io.c; 

FILE MODES 

The working file inherits the read and execute pomissions from the RCS file. In addition, the owner 
write permission is turned on, unless the file is checked out unlocked and locking is set to strict (see res 

(D). 

If a file with the name of the wes'king file exists already and has write permission, co aborts the 
checkout if -q is given, or asks whether to abort if -q is not given. If the existing working file is not 
writable, it is deleted before the checkout 

FILES 

The caller of the command must have write permission in the working directory, read permission for 
the RCS file, and either read permissiem (for reading) or read/write permission (for locking) in the 
directory which contains the RCS file. 

A number of temporary files are created. A semaphore file is created in the directory of the RCS file to 
prevent simultaneous update. 

IDENTIFICATION 

Author Walter F. Tichy, Purdue University, West Lafayette, IN, 47907. 

Revision Numb^: 3.1 ; Release Date: 83/04/04 . 

Copyright © 1982 by Waltw F. Tichy. 

SEE ALSO 

ci (1), ident(l), res (1), resdiff (1), resmerge (1), rlog (1), resfile (5). 

Walter F. Tichy, "Design, Implementiuion, and Evaluation of a Revision Control System," in Proceed¬ 
ings of the 6th International Conference on Software Engineering, IEEE, Tokyo, Sept. 1982. 

LIMITATIONS 

The option -d gets confused in some circumstances, and accepts no date before 1970. There is no way 
to suppress the expansion of keywords, except by writing them differently. In nroff and troff, this is 
done by embedding the null-character *N&’ into the keyword. 

BUGS 

The option -j does not work for files that contain lines with a single 
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NAME 

col - filter reverse line feeds 

SYNOPSIS 

col [ -bfh ] 

DESCRIPTION 

Col reads the standard input and writes the standard output. It performs the line overlays implied by 
reverse line feeds (ESC-7 in ASCII) and by forward and revise half line feeds (ESC-9 and ESC-8). 
Col is particularly useful fw filtering multicolumn output made with the ‘.it’ command of nroffmd. out¬ 
put resulting from use of the tbl{\) preprocessor. 

Although col accepts half line motions in its input, it normally does not emit them on output. Instead, 
text that would appear betwe^ lines is moved to the next Iowct full line boundary. This treatment can 
be suppressed by the -f (fine) option; in this case the output from col may contain forward half line 
feeds (ESC-9), but will still never contain either kind of reverse line motion. 

If the -b option is given, col assumes that die output device in use is not capable of backspacing. In 
this case, if several characters are to appear in the same place, only the last one read will be taken. 

The control characters SO (ASCII code 017), and SI (016) are assumed to start and end text in an alter¬ 
nate character set. The character set (primary or alternate) associated with each printing character read 
is remembered; on output, SO and SI characters are generated where necessary to maintain the correct 
treatment of each character. 

If the -h option is given, col converts white space to tabs to shorten printing time. 

All control characters are removed fixim the input except space, backspace, tab, return, newline, ESC 
(033) followed by one of 7, 8, 9, SI, SO, and VT (013). This last character is an alternate form of full 
reverse line feed, for compatibility with some other hardware conventions. All other non-printing char¬ 
acters are ignored. 

SEE ALSO 

troff(l), tbl(l) 

BUGS 

Can’t back up more than 128 lines. 

No more than 800 characters, including backsi»ces, on a line. 
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NAME 

colcrt - filter nroff output for CRT previewing 
SYNOPSIS 

colcrt [ - ] [ -2 ] [ file ... ] 

DESCRIPTION 

Colcrt provides virtual half-line and reverse line feed sequences for terminals without such capability, 
and on which overstriking is destructive. Half-line characters and underlining (changed to dashing 
are placed on new lines in between the normal output lines. 

The optional - suppresses all underlining. It is especially useful for previewing allboxed tables from 
tbliX). 

The option -2 causes all half-lines to be printed, effectively double spacing the output Normally, a 
minimal space output format is used which will suppress empty lines. The program never suppresses 
two consecutive empty lines, however. The -2 option is useful for sending output to the line printer 
when the output contains superscripts and subscripts which would otherwise be invisible. 

A typical use of colcrt would be 

tbl exum2.n I nroff -ms I colcrt - I more 

SEE ALSO 

nroff/troff(l), col(l), more(l), ul(l) 

BUGS 

Should fold underlines onto blanks even with the option so that a true underline character would 
show; if we did this, however, colcrt wouldn’t get rid of cu'd underlining completely. 

Can’t back up more than 102 lines. 

General overstriking is lost; as a special case T overstruck with or underline becomes *+’. 

Lines are trimmed to 132 characters. 

Some provision should be made for processing superscripts and subscripts in documents which are 
already double-spaced. 
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NAME 

colrm - remove columns from a file 
SYNOPSIS 

colrm [ startcol [ endcol ] ] 

DESCRIPTION 

Colrm removes selected columns from a file. Input is taken from standard input. Output is sent to 
standard output. 

If called with one parameter the columns of each line will be removed starting with the specified 
column. If called with two parameters the columns from the first column to the last column will be 
removed. 

Column numbering starts with column 1. 

SEE ALSO 

expand(l) 
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NAME 

comm - select or reject lines common to two sorted files 
SYNOPSIS 

comm [ - [ 123 ] ] filel file! 

DESCRIPTION 

Comm reads and>i/e2. which should be ordered in ASCII collating sequence, and produces a three 
column output: lines only m filel; lines only in file!; and lines in both files. The filename means 
the standard input 

Rags 1, 2, or 3 suppress printing of the corresponding column. Thus comm -12 prints only the lines 
common to the two files; comm -23 prints only lines in the first file but not in the second; comm -123 
is a no-op. 

SEE ALSO 

cmp(l), diff(l), uniq(l) 
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NAME 

compress, uncompress, zcat - compress and expand data 
SYNOPSIS 

compress [ -f ] [ -v ] [ -c ] [ -b bits ] [ name ... ] 
uncompress [ -f ] [ -v ] [ -c ] [ name ... ] 
zcat [ name ... ] 

DESCRIPTION 

Compress reduces the size of the named files using adaptive Lempel-Ziv coding. Whenever possible, 
each file is replaced by one with the extension JZ, while keeping the same ownership modes, access and 
modification times. If no files are specified, the standard input is compressed to the standard output. 
Compressed files can be restored to their original form using uncompress or zcat. 

The -f option will force compression of name, even if it does not actually shrink or the corresponding 
nameZ file already exists. Except when run in the background under Ibin/sh, if -f is not given the user 
is prompted as to whether an existing name.Z file should be overwritten. 

The -c (“cat”) option makes compress/uncompress write to the standard ouq)ut; no files are changed. 
The nondestructive behavior of zcat is identical to that of uncompress -c. 

Compress uses the modified Lempel-Ziv algorithm popularized in ”A Technique for High Performance 
Data Compression", Terry A. Welch, IEEE Computer, vol. 17, no. 6 (June 1984), pp. 8-19. Common 
substrings in the file are first replaced by 9-bit codes 257 and up. When code 512 is reached, the algo¬ 
rithm switches to 10-bit codes and continues to use more bits until the limit specified by the -b flag is 
reached (default 16). Bits must be between 9 and 16. The default can be changed in the source to 
allow compress to be run on a smaller machine. 

After the bits limit is attained, compress periodically checks the compression ratio. If it is increasing, 
compress continues to use the existing c^e dictionary. However, if the compression ratio decreases, 
compress discards the table of substrings and rebuilds it from scratch. This allows the algorithm to 
adapt to the next "block" of the file. 

Note that the -b flag is omitted for uncompress, since the bits parameter specified during compression 
is encoded within the output, along with a magic numbw to ensure that neither decompression of ran¬ 
dom data nor recompiession of compressed data is attempted. 

The amount of compression obtained depends on the size of the input, the number of bits per code, and 
the distribution of common substrings. Typically, text such as source code or English is reduced by 
50-^%. Compression is generally much better than that achieved by Huffman coding (as used in 
pack), or adaptive Huffman coding {compact), and takes less time to compute. 

The -V option causes the printing of the percentage reduction of each file. 

If an error occurs, exit status is 1, else if the last file was not compressed because it became larger, the 
status is 2; else the status is 0. 

DIAGNOSTICS 

Usage: compress [-fvc] [-b maxbits] [file ...] 

Invalid options were specified on the command line. 

Missing maxbits 

Maxbits must follow -b. 
file', not in compressed format 

The file specified to uncompress has not been compressed. 
file: compressed with xx bits, can only handle yy bits 

File was compressed by a program that could deal with more bits than the compress 
code on this machine. Recompress the file with smaller bits, 
file: already has .Z suffix -- no change 

The file is assumed to be already compressed. Rename the file and try again. 
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BUGS 


file: filename too long to tack on .Z 

The file cannot be compressed because its name is longer than 12 characters. 
Rename and try again. This message does not occur on BSD systems. 
file already exists; do you wish to overwrite (y or n)? 

Resptmd "y" if you want the output file to be replaced; "n" if not 
uncompress: corrupt input 

A SIGSEGV violation was detected which usually means that the input file is cor¬ 
rupted. 

Compression: xxjcx% 

Percentage of the input saved by compression. (Relevant only for -v.) 

- not a regular file: unchanged 

When the input file is not a regular file, (e.g. a directory), it is left unaltered. 

" has XX other links: unchanged 

The input file has links; it is left unchanged. See /n(l) for more information. 

“ file unchanged 

No savings is achieved by compression. The input remains virgin. 


Although compressed files are compatible between machines with large memory, -bl2 should be used 
for file transfer to architectures with a small process data space (64KB or less, as exhibited by the DEC 
PDP series, the Intel 80286, etc.) 

compress should be more flexible about the existence of the suffix. 
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NAME 

core - format of memory image file 
SYNOPSIS 

#iiidude <sys/paraiii.li> 

DESCRIPTION 

The UNIX System writes out a memory image of a terminated process when any of various errors 
occur. See sigvecil) for the list of reasons; the most common are memory vidarions, illegal instnic- 
tions« bus errors, and user-generated quit signals. The memory image is called ‘core’ and is written in 
the process’s working directory (provided it can be; normal access controls s^ply). 

The maximum size of a core file is limited by setrlimit{2). Files which would be larger than the limit 
are not created. 

The core file ctmsists of the u. area, whose size (in pages) is defined by the UPAGES manife^ in the 
<syslparam.h> file. The u. area starts with a user structure as given in <sysluser.h>. The remainder of 
the core file consists first of the data pages and then the stack pages of the process image. The amount 
of data space image in the core file is given (in pages) by the variable ujisize in the u. area. The 
amount of stack image in the core file is given (in pages) by the variable u_ssize in the u. area. The 
size of a “page” is given by the constant NBPG (also firtun <syslparamJi>). 

In general the debugger adb(i) is sufficient to deal with ctne images. 

SEE ALSO 

adb(l), dbx(l), sigvec(2), setrlimit(2) 
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NAME 

q) - copy 

SYNOPSIS 

cp [ -ip ] filel file2 

cp [ -ipr ] file ... directory 
DESCRIPTION 

Filel is copied onto file2. By default, the mode and owner of file2 are preserved if it already existed; 
otherwise the mode of the source file modified by the current umask(2) is used. The -p option causes 
cp to attempt to preserve (duplicate) in its copies the modification times and modes of the source files, 
ignoring the present umask. 

In the second form, one c«r more files are copied into the directory with their original file-names. 

Cp refuses to copy a file onto itself. 

If the -4 option is specified, cp will prompt the user with the name of the file whenever the copy will 
cause an old file to be overwritten. An answer of ’y’ will cause cp to continue. Any other answer will 
prevent it from overwriting the file. 

If the -r option is specified and any of the source files are directories, cp copies each subtree rooted at 
that name; in this case the destination must be a directory. 

EUNICE NOTES 

Cp requires that files be kept to one version by turning EUNICE_1VERSI0N ON. See 
letclemiceleunice.com. 

SEE ALSO 

cat(l), mv(l) 
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NAME 

crypt - encode/decode 

SYNOPSIS 

crypt [ password ] 

DESCRIPTION 

Crypt reads from the standard input and writes on the standard output The password is a key that 
selects a particular transformation. If no password is given, crypt demands a key from the termini and 
turns off printing while the key is being typed in. Crypt encrypts and decrypts with the same key: 

crypt key <clear >cypher 
crypt key <cypher I pr 

will print the clear. 

Files encrypted by crypt are compatible with those treated by the editor ed in encryption mode. 

The security of encrypted files depends (mi three factors: the fundamental method must be hard to 
solve; direct search of the key space must be infeasible; ‘sneak paths’ by which keys or cleartext can 
become visible must be minimiz^ 

Crypt implements a one-rotor machine designed along the lines of the German Enigma, but with a 
256-element rotor. Methods of attack on such machines are known, but not widely; moreover the 
amount of work required is likely to be large. 

The transformation of a key into the internal settings of the machine is deliberately designed to be 
expensive, i.e. to take a substantial fraction of a second to compute. However, if keys are restricted to 
(say) three lower-case letters, then encrypted files can be read by expending only a substantial fraction 
of five minutes of machine time. 

Since the key is an argument to the crypt command, it is potentially visible to users executing pj(l) or 
a derivative. To minimize this possibility, crypt takes care to destroy any record of the key immedi¬ 
ately upon entry. No doubt the choice of keys and key security are the most vulnerable aspect of crypt. 

FILES 

/dev/tty for typed key 

SEE ALSO 

ed(l), makekey(8) 

BUGS 

There is no warranty of merchantability nor any warranty of fitness for a particular purpose nor any 
other warranty, either express or implied, as to the accuracy of the enclosed matoials or as to their sui¬ 
tability for any particular purpose. Accordingly, Bell Telqjhone Laboratories assumes no responsibility 
for their use by the recipient. Further, Bell Laboratories assumes no obligation to furnish any assis¬ 
tance of any kind whatsoever, or to furnish any additional information or documentation. 
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NAME 

csh - a shell (command interpreter) with C-like syntax 
SYNOPSIS 

csh [ -cefinstvVxX ] [ arg ... ] 


DESCRIPTION 

Csh is a first implementation of a command language interpreter incorporating a history mechanism (see 
History Substitutions), job control facilities (see Jobs), interactive file name and user name completion 
(see File Name Completion), and a C-like syntax. So as to be able to use its Job control facilities, 
users of csh must (and automatically) use the new tty driver fully described in tty {A). This new tty 
driver allows generation of interrupt characters fi-om the keyboard to tell jobs to stop. See stty(l) for 
details on setting options in the new tty driver. 

An instance of csh begins by executing commands from the file ‘.cshrc’ in the home directory of the 
invoker. If this is a login shell then it also executes ccmimands from the file Mogin’ there. It is typical 
for usCTS on crt’s to put the command “stty crt” in their .login file, and to also invoke tset(l) there. 

In the normal case, the shell will then begin reading commands from the terminal, prompting with *% ’. 
Processing of arguments and the use of the shell to process files containing command scripts will be 
described later. 


The shell then repeatedly performs the following actions: a line of c(»nmand input is read and broken 
into words. This sequence of words is placed on the command history list and then parsed. Finally 
each command in the current line is executed. 

When a login shell terminates it executes commands from the file ‘.logout’ in the users home directory. 
Lexical structure 


The shell splits input lines into words at blanks and tabs with the following exceptions. The characters 
*&’ ‘I’ ‘<’ *>’ *(’ ‘)* form separate words. If doubled in *&&’, ‘I I’, *«’ or *»’ these pairs form 

single words. These parser metacharacters may be made part of other words, or prevented their special 
meaning, by preceding them with V. A newline preceded by a *\’ is equivalent to a blank. 


In addition strings enclosed in matched pairs of quotations, or form parts of a word; meta¬ 
characters in these strings, including blanks and tabs, do not form separate words. These quotations 
have semantics to be described subsequently. Within pairs of or characters a newline preceded 
by a V gives a true newline character. 


When the shell’s input is not a terminal, the character *#’ introduces a comment which continues to the 
end of the input line. It is prevented this special meaning when preceded by ‘V and in quotations using 


Commands 


A simple command is a sequence of words, the first of which specifies the command to be executed. A 
simple command or a sequence of simple commands separated by ‘I’ characters forms a pipeline. The 
output of each command in a pipeline is connected to the input of the next. Sequences of pipelines 
may be separated by and are then executed sequentially. A sequence of pipelines may be executed 
without immediately waiting for it to terminate by following it with an *&’. 

Any of the above may be placed in ‘(’ *)’ to form a simple command (which may be a component of a 
pipeline, etc.) It is also possible to separate pipelines with ‘I I’ or *&&’ indicating, as in the C language, 
that the second is to be executed only if the first fails or succeeds respectively. (See Expressions.) 

Jobs 


The shell associates a job with each pipeline. It keeps a table of current jobs, printed by the jobs com¬ 
mand, and assigns them small integer numbers. When a job is started asynchronously with *&’, the 
shell prints a line which looks like: 
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[1] 1234 

indicating that the job which was started asynchronously was job number 1 and had one (top-level) pro¬ 
cess, whose process id was 1234. 

If you are running a job and wish to do something else you may hit the key "Z (control-Z) which sends 
a STOP signal to the current job. The shell will then normally indicate that the job has been ‘Stopped’, 
arid print another prompt. You can then manipulate the state of this job, putting it in the background 
with the bg command, or run some other commands and then eventually bring the job back into the 
foreground with the foreground command/g. A "Z takes effect immediately and is like an interrupt in 
that pending output and unread input are discarded when it is typed. There is another special key "Y 
which does not generate a STOP signal until a program attempts to read(2) it. This can usefully be 
typed ahead when you have prepared some commands for a job which you wish to stop after it has read 
them. 

A job being run in the background will stop if it tries to read from the terminal. Background jobs are 
normally allowed to produce output, but this can be disabled by giving the command “stty tostop”. If 
you set this tty option, then background jobs will stop when they try to produce output like they do 
when they try to read input. 

There are several ways to refer to jobs in the shell. The character introduces a job name. If you 
wish to refer to job number 1, you can name it as *%!’. Just naming a job brings it to the foreground; 
thus ‘%r is a synonym for ‘fg %1’, bringing job 1 back into the foreground. Similarly saying ‘%1 &’ 
resumes job 1 in the background. Jobs can also be named by prefixes of the string typed in to start 
them, if these prefixes are unambiguous, thus *%ex’ would normally restart a suspended ex(l) job, if 
there were only one suspended job whose name began with the string ‘ex’. It is also possible to say 
‘%?string’ which specifies a job whose text contains string, if there is only one such job. 

The shell maintains a notion of the current and previous jobs. In output pertaining to jobs, the current 
job is marked with a ‘+’ and the previous job with a The abbreviation ‘%+’ refers to the current 
job and *%-’ refers to the previous job. For close analogy with the syntax of the history mechanism 
(described below), ‘%%’ is also a synonym for the current job. 

Status reporting 

piis shell learns immediately whenever a process changes state. It normally informs you whenever a 
job bwomes blocked so that no further progress is possible, but only just before it prints a prompt. 
This is done so that it does not otherwise disturb your work. If, however, you set the shell variable 
notify, the shell will notify you immediately of changes of status in background jobs. There is also a 
shell command notify which marks a single process so that its status changes will be immediately 
reported. By default notify marks the current process; simply say ‘notify’ after starting a background 
job to mark it. 

When you try to leave the shell while jobs are stopped, you will be warned that ‘You have stopped 
jobs.’ You may use the jobs command to see what they are. If you do this or immediately try to exit 
again, the shell will not warn you a second time, and the suspended jobs will be terminated. 

File Name Completion 

When the file name completion feature is enabled by setting the shell variable flee (see set), esh will 
interactively complete file names and user names from unique prefixes, when they are input from the 
terminal followed by the escape character (the escape key, or control-[). For example, if the current 
directory looks like 

DSC.OLD bin cmd 

DSC.NEW Chaosnet emtest 

bench class dev 

and the input is 

% vi ch<escape> 

esh will complete the prefix “ch” to the only matching file name “chaosnet”, changing the input line 


lib xmpl.c 

mail xmpl.o 

mbox xmpl.out 


2 



CSH(l) 


UNIX Prognunmer’s Manual 


CSH(l) 


to 


% vi Chaosnet 


However, given 

% vi D<escape> 
csh will only expand the input to 
% vi DSC. 

and will sound the terminal bell to indicate that the expansion is incomplete, since there are two file 
names matching the prefix “D”. 


If a partial file name is followed by the end-of-file character (usually control-D), then, instead of com¬ 
pleting the name, csh will list all file names matching the prefix. For example, the input 
% vi D<control-D> 

causes all files beginning with “D” to be listed: 

DSCJ^W DSC.OLD 
while the input line remains unchanged. 


The same system of escape and end-of-file can also be used to expand partial user names, if the word to 
be completed (or listed) begins with the character For example, typing 
cd “ro<control-D> 
may produce the expansion 
cd ’root 


The use of the terminal bell to signal mors or multiple matches can be inhibited by setting the variable 
nobeep. 

Normally, all files in the particular directory am candidates for name completion. Files with certain 
suffixes can be excluded from consideration by setting the variable jignore to the list of suffixes to be 
ignored. Thus, if /ignore is set by the command 
% set fignore = (.0 .out) 

then typing 

% vi x<escape> 
would result in the completion to 
% vi xmpl.c 

ignoring the files "xmpLo" and "xmpl.out". However, if the only completion possible requires not 
ignoring these suffixes, then they are not ign(»ed. In addition, jignore does not affect the listing of file 
names by control-D. All files are listed regardless of their suffixes. 

Substitutions 


We now describe the various transformations the shell performs on the input in the order in which they 
occur. 


History substitutions 

History substitutions place words from previous command input as portions of new commands, making 
it easy to repeat commands, repeat arguments of a previous command in the current command, or fix 
spelling mistakes in the previous command with little typing and a high degree of confidence. History 
substitutions begin with the character *!’ and may begin anywhere in the input stream (with the proviso 
that they do not nest.) This *!’ may be preceded by an ‘V to prevent its special meaning; for conveni¬ 
ence, a *!’ is passed unchanged when it is followed by a blank, tab, newline, *=’ or *(’• (History substi¬ 
tutions also occur when an input line begins with ‘T’. This special abbreviation wiU be described 
later.) Any input line which contains history substitution is echoed on the terminal before it is executed 
as it could have been typed without history substitution. 

Commands input from the terminal which consist of one or more words are saved on the history list. 
The history substitutions reintroduce sequences of words from these saved commands into the input 
stream. The size of which is controlled by the history variable; the previous command is always 
retained, regardless of its value. Commands are numbered sequentially from 1. 
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For definiteness, consider the following output fiom the history command: 

9 write michael 

10 ex write.c 

11 cat oldwrite.c 

12 diff ♦write.c 

The commands are shown with their event numbers. It is not usually necessary to use event numbers, 
but the current event number can be made part of the prompt by placing an *!’ in the prompt string. 

With the current event 13 we can refer to previous events by event number ‘Ill’, relatively as in ‘!-2’ 
(referring to the same event), by a prefix of a command word as in ‘!d’ for event 12 or ‘!wri’ for event 
9, or by a string contained in a word in the command as in ‘!?mic?’ also referring to event 9. These 
forms, without further modification, simply reintroduce the words of the specified events, each separated 
by a single blank. As a special case *!!* refers to the previous command; thus *!!’ alone is essentially a 
redo. 

To select words from an event we can follow the event specification by a and a designator for the 
desired words. The words of an input line aio numb^od from 0, the first (usually command) word 
being 0, the second word (first argument) being 1, etc. The basic word designators are: 

0 first (command) word 

n n ’th argument 

T first argument, i.e.‘1’ 

$ last argument 

% word matched by (immediately preceding) ls7 search 

x-y range of words 

-y abbreviates ‘0-y ’ 

* abbreviates ‘T-$’, or nothing if only 1 word in event 

X* abbreviates 

X- like ‘x*’ but omitting word *$’ 

The separating the event specification from the word designator can be omitted if the argument 
selector begins with a ‘T’, *$’, *♦’ or *%’. After the optional word designator can be placed a 
sequence of modifiers, each preceded by a The following modifiers are defined: 

h Remove a trailing pathname component, leaving the head, 

r Remove a trailing ‘.xxx* component, leaving the root name, 

e Remove all but the extension ‘.xxx’ part. 

s/l/rf Substitute / for r 

t Remove all leading pathname components, leaving the tail. 

& Repeat the previous substitution, 

g Apply the change globally, prefixing the above, e.g. ‘g&’. 

p Print the new command W do not execute it 

q Quote the substituted words, preventing further substitutions. 

X Like q, but break into words at blanks, tabs and newlines. 

Unless preceded by a ‘g’ the modification is applied only to the first modifiable word. With substitu¬ 
tions, it is an error for no word to be applicable. 

The left hand side of substitutions are not regular expressions in the sense of the editors, but rather 
strings. Any character may be used as the delimiter in place of */’; a ‘V quotes the delimiter into the / 
and r strings. The character *&’ in the right hand side is replaced by Ae text from the left. A ‘V 
quotes *&’ also. A null / uses the previous string either from a / or firom a contextual scan string s in 
‘!?5?’. The trailing delimiter in the substitution may be omitted if a newline follows immediately as 
may the trailing *?’ in a contextual scan. 
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A history reference may be given without an event specification, e.g. *!$’. In this case the reference is 
to the previous command unless a previous history reference occurred on the same line in which case 
this form repeats the previous reference. Thus ‘!?foo?T !$’ gives the first and last arguments from the 
command matching ‘?foo?’. 

A special abbreviation of a history reference occurs when the first non-blank character of an input line 
is a ‘t*. This is equivalent to ‘!:st’ providing a convenient shorthand for substitutions on the text of 
the previous line. Thus ‘tlbtlib’ fixes the spelling of Tib’ in the previous command. Finally, a history 
substitution may be surrounded with and *}’ if necessary to insulate it from the characters which fol¬ 
low. Thus, after ‘Is -Id "paul’ we might do ‘!{l}a’ to do ‘Is -Id "paula’, while ‘!la’ would look for a 
command starting ‘la’. 

Quotations with ' and " 

The quotatitm of strings by ‘'’ and ‘"’ can be used to prevent all or some of the remaining substitutions. 
Strings enclosed in ‘'’ are prevented any further interpretation. Strings enclosed in may be 
expanded as described below. 

In both cases the resulting text becomes (all or part of) a single word; only in one special case (see 
Command Substitition below) does a ‘”* quoted string yield parts of more than one word; quoted 
strings never do. 

Alias substitution 

The shell maintains a list of aliases which can be established, displayed and modified by the alias and 
unalias commands. After a command line is scanned, it is parsed into distinct commands and the first 
word of each command, left-to-right, is checked to see if it has an alias. If it does, then the text which 
is the alias for that command is reread with the history mechanism available as though that command 
were the previous input line. The resulting words replace the command and argument list. If no refer¬ 
ence is made to the history list, then the argument list is left unchanged. 

Thus if the alias for ‘Is’ is ‘Is -1’ the command ‘Is /usr’ would map to *ls -1 /usr’, the argument list 
here being undisturbed. Similarly if the alias for ‘lookup’ was ‘grep !t /etc/passwd’ then ‘lookup bill’ 
would map to ‘grep bill /etc/passwd’. 

If an alias is found, the word transformation of the input text is performed and the aliasing process 
begins again on the reformed input line. Looping is prevented if the first word of the new text is the 
same as the old by flagging it to prevent further aliasing. Other loops are detected and cause an error. 

Note that the mechanism allows aliases to introduce parser metasyntax. Thus we can ‘alias print 'pr\!* 

I Ipr'’ to make a command which pr’s its arguments to the line printer. 

Variable substitution 

The shell maintains a set of variables, each of which has as value a list of zero or more words. Some 
of these variables are set by the shell or referred to by it. For instance, the argv variable is an image of 
the shell’s argument list, and words of this variable’s value are referred to in special ways. 

The values of variables may be displayed and changed by using the set and unset commands. Of the 
variables referred to by the shell a number are toggles; the shell does not care what their value is, only 
whether they are set or not. For instance, the verbose variable is a toggle which causes command input 
to be echoed. The setting of this variable results from the -v command line option. 

Other operations treat variables numerically. The ‘@’ command permits numeric calculations to be 
performed and the result assigned to a variable. Variable values are, however, always represented as 
(zero or more) strings. For the purposes of numeric operations, the null string is considered to be zero, 
and the second and subsequent words of multiword values are ignored. 

After the input line is aliased and parsed, and before each command is executed, variable substitution is 
performed keyed by ‘$’ characters. This expansion can be prevented by preceding the ‘$’ with a ‘\’ 
except within ‘"’s where it always occurs, and within ‘'’s where it never occurs. Strings quoted by 
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are interpreted later (see Command substitution below) so *$’ substitution does not occur there until 
later, if at all. A *$’ is passed unchanged if followed by a blank, tab, or end-of-line. 

Input/output redirections are recognized before variable expansion, and are variable expanded 
separately. Otherwise, the command name and entire argument list are expanded together. It is thus 
possible for the first (command) word to this point to generate more than one word, the first of which 
becomes the command name, and the rest of which become arguments. 

Unless enclosed in or given the ‘:q’ modifier the results of variable substitution may eventually be 
command and filename substituted. Within a variable whose value consists of multiple words 
expands to a (portion of) a single word, with the words of the variables value separated by blanks. 
When the ‘:q’ modifier is applied to a substitution the variable will expand to multiple words with each 
word separated by a blank and quoted to prevent later command or filename substitution. 

The following metasequences are provided for introducing variable values into the shell input. Except 
as noted, it is an error to reference a variable which is not set. 

$name 

${name} 

Are replaced by the words of the value of variable name, each separated by a blank. Braces insu¬ 
late name from following characters which would otherwise be part of it Shell variables have 
names consisting of up to 20 letters and digits starting with a letter. The underscore character is 
considered a letter. 

If name is not a shell variable, but is set in the environment, then that value is returned (but : 
modifiers and the other forms given below are not available in this case). 

$name[selector] 

${name[selector]} 

May be used to select only some of the words from the value of name. The selector is subjected 
to *$’ substitution and may consist of a single number or two numbers separated by a The 
first word of a variables value is numbered ‘1’. If the first number of a range is omitted it 
defaults to ‘1’. If the last member of a range is omitted it defaults to ‘$#name’. The selector 
selects all words. It is not an error for a range to be empty if the second argument is omitted or 
in range. 

$#name 

${#name) 

Gives the number of words in the variable. This is useful for later use in a ‘[selector]’. 

$0 

Substitutes the name of the file from which command input is being read. An error occurs if the 
name is not known. 

Snumber 
$ (number) 

Equivalent to ‘$argv[number]’. 

$♦ 

Equivalent to ‘$argv[*]’. 

The modifiers ‘:h’, ‘:t’, ‘:r’, ‘:q’ and ‘:x’ may be applied to the substitutions above as may ‘:gh’, ‘:gt’ 
and ‘:gr’. If braces ’}’ appear in the command form then the modifiers must appear within the 

braces. The current implementation allows only one modifier on each *$’ expansion. 

The following substitutions may not be modified with modifiers. 

$?name 

${?name} 

Substitutes the string ‘1’ if name is set, ‘0’ if it is not. 
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$?0 

Substitutes ‘1’ if the current input filename is known, ‘0’ if it is not 

$$ 

Substitute the (decimal) process number of the (parent) shell. 

$< 

Substitutes a line from the standard input, with no further interpretation thereafter. It can be used 
to read from the keyboard in a shell script 

Command and filename substitution 

The remaining substitutions, command and filename substitution, are applied selectively to the argu¬ 
ments of builtin commands. This means that portions of expressions which are not evaluated are not 
subjected to these expansions. For commands which are not internal to the shell, the command name is 
substituted separately from the argument list. This occurs very late, after input-output redirection is 
performed, and in a child of the main shell. 

Command substitution 

Command substitution is indicated by a command enclosed in *'*. The output from such a command is 
normally broken into separate words at blanks, tabs and newlines, with null words being discarded, this 
text then replacing the original string. Within ‘"*s, only newlines force new words; blanks and tabs are 
preserved. 

In any case, the single final newline does not fOTce a new word. Note that it is thus possible for a com¬ 
mand substitution to yield only part of a word, even if the command outputs a complete line. 

FUename substitution 

If a word contains any of the characters *♦’, *?’, ‘[’ or or begins with the character then that 
word is a candidate for filename substitution, also known as ‘globbing’. This word is then regarded as 
a pattern, and replaced with an alphabetically sorted list of file names which match the pattern. In a list 
of words specifying filename substitution it is an error for no pattern to match an existing file name, but 
it is not required for each pattern to match. Only the metacharacters *♦’, *?’ and *[’ imply pattern 
matching, the characters *” and *{’ being more akin to abbreviations. 

In matching filenames, the character at the beginning of a filename or immediately following a ‘/’.as 
well as the character T must be matched explicitly. The character matches any string of characters, 
including the null string. The character *?’ matches any single charact^. The sequence *[...]’ matches 
any one of the characters enclosed. Within *[...]’, a pair of characters separated by matches any 
character lexically between the two. 

The character ’ at the beginning of a filename is used to refer to home directories. Standing alone, 
i.e. ’ it expands to the invokers home directory as reflected in the value of the variable home. When 
followed by a name consisting of letters, digits and characters the shell searches for a user with that 
name and substitutes their home directory; thus “"ken’ might expand to Vusr/ken’ and ‘~ken/chmach’ 
to 7usr/ken/chmach’. If the character is followed by a character other than a letter or 7’ or appears 
not at the beginning of a word, it is left undisturbed. 

The metanotation ‘a{b,c,d}e’ is a shorthand for *abe ace ade’. Left to right order is preserved, with 
results of matches being sorted separately at a low level to preserve this order. This construct may be 
nested. Thus “■source/sl/{oldls,ls}.c’ expands to 7usr/source/sl/oldls.c /usr/source/sl/ls.c’ whether or 
not these files exist without any chance of error if the home directory for ‘source’ is ‘/usr/source’. 
Similarly ‘../{memo,*box)’ might expand to ‘../memo ../box .ymbox’. (Note that ‘memo’ was not 
sorted with the results of matching ‘♦box’.) As a special case and ‘{)’ are passed undisturbed. 
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Input/output 

The standard input and standard output of a command may be redirected with the following syntax: 

< name 

Open file name (which is first variable, command and filename expanded) as the standard input. 
« word 

Read the shell input up to a line which is identical to word. Word is not subjected to variable, 
filename or command substitution, and each input line is compared to word before any substitu¬ 
tions are done on this input line. Unless a quoting *\’, or *'* appears in word variable and 
command substitution is performed on the intervening lines, allowing V to quote ‘$’, ‘V and *'*. 
Commands which are substituted have all blanks, tabs, and newlines preserved, except for the 
final newline which is dropped. The resultant text is placed in an anonymous temporary file 
which is given to the command as standard input. 

> name 
>! name 
>& name 
>&! name 

The file name is used as standard output If the file does not exist then it is created; if the file 
exists, its is truncated, its previous contents being lost 

If the variable noclobber is set, then the file must not exist or be a character special file (e.g. a 
terminal or ‘/dev/null’) or an error results. This helps prevent accidental destruction of files. In 
this case the *!’ forms can be used and suppress this check. 

The forms involving *&’ route the diagnostic output into the specified file as well as the standard 
ouq)ut. Name is expanded in the same way as *<’ input filenames are. 

» name 
»& name 
»! name 
»&! name 

Uses file name as standard output like *>’ but places output at the end of the file. If the variable 
noclobber is set, then it is an error fOT the file not to exist unless one of the *!’ forms is given. 
Otherwise similar to *>’. 

A command receives the environment in which tl» shell was invoked as modified by the input-output 
parameters and the presence of the command in a pipeline. Thus, unlike some previous shells, com¬ 
mands run from a file of shell commands have no access to the text of the commands by default; rather 
they receive the original standard input of the shell. The *«’ mechanism should be used to present 
inline data. This permits shell command scripts to function as components of pipelines and allows the 
shell to block read its input Note that the default standard input for a command run detached is not 
modified to be the empty file ‘/dev/null’; rather the standard input remains as the original standard input 
of the shell. If this is a terminal and if the process attempts to read from the terminal, then the process 
will block and the user will be notified (see Jobs above). 

Diagnostic output may be directed through a pipe with the standard output. Simply use the form ‘I&’ 
rather than just ‘I’. 

Expressions 

A number of the builtin commands (to be (tescribed subsequently) take expressions, in which the opera¬ 
tors are similar to those of C, with the same precedence. These expressions appear in the exit, if, 
and while commands. The following operator are available: 

I I && I t & == != =” !'■<=>=<>«» + _♦/% I - ( ) 
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Here the precedence increases to the right, ’ *!=’ ‘="” and M"’, *<=’ *>=’ *<’ and *>’, *«’ and *»’, 
*+’ and *♦’ V’ and *%’ being, in groups, at the same level. The ‘==’ ‘!=’ *="’ and operators 
compare their arguments as strings; all others operate on numbers. The operators ‘=''’ and *!"’ are like 
*!=’ and *=’ except that the right hand side is a pattern (containing, e.g. ‘*’s, ‘?’s and instances of 
*[...]’) against which the left hand operand is matched. This reduces the need for use of the switch 
statement in shell scripts when all that is really needed is pattern matching. 


Strings which begin with ‘0’ are considered octal numbers. Null or missing arguments are considered 
‘O’. The result of all expressions are strings, which represent decimal numbers. It is important to note 
that no two components of an expression can appear in the same word; except when adjacent to com¬ 
ponents of expressions which are syntactically significant to the parser (*&’ ‘I’ *<’ *>’ ‘(’ ‘)’) they 
should be surrounded by spaces. 


Also available in expressions as primitive operands are command executions enclosed in ‘ ’ and ‘} ’ and 
file enquiries of the form ‘-7 name’ where / is one of: 


r read access 

w write access 

X execute access 

e existence 

o ownership 

z zero size 

f plain file 

d directory 

The specified name is command and filename expanded and then tested to see if it has the specified 
relationship to the real user. If the file does not exist or is inaccessible then all enquiries return false, 
i.e. ‘O’. Command executions succeed, returning true, i.e. ‘1’, if the command exits with status 0, oth¬ 
erwise they fail, returning false, i.e. ‘O’. If more detailed status information is required then the com¬ 
mand should be executed outside of an expression and the variable status examined. 

Control flow 


The shell contains a number of commands which can be used to regulate the flow of control in com¬ 
mand files (shell scripts) and (in limited but useful ways) from terminal input These commands all 
operate by forcing the shell to reread or skip in its input and, due to the implementation, restrict the 
placement of some of the commands. 

The foreach, switch, and while statements, as well as the if-then-else form of the if statement require 
that the major keywords appear in a single simple command on an input line as shown below. 

If the shell’s input is not seekable, the shell buffers up input whenever a loop is being read and per¬ 
forms seeks in this internal buffer to accomplish the rereading implied by the loop. (To the extent that 
this allows, backward goto’s will succeed on non-seekable inputs.) 

Builtin commands 

Builtin commands are executed within the shell. If a builtin command occurs as any component of a 
pipeline except the last then it is executed in a subshell. 

alias 

alias name 
alias name wordlist 

The first form prints all aliases. The second form prints the alias for name. The final form 
assigns the specified wordlist as the alias of name; wordlist is command and filename substituted. 
Name is not allowed to be alias or unalias. 
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alloc 

Shows the amount of dynamic memory acquired, broken down into used and free memory. With 
an argument shows the number of free and used blocks in each size category. The categories 
start at size 8 and double at each step. This command’s output may vary across system types, 
since systems other than the VAX may use a different memory allocator, 
bg 

bg %job... 

Puts the current or specified jobs into the background, continuing them if they were stopped. 

break 

Causes execution to resume after the end of the nearest enclosing foreach or while. The remain¬ 
ing commands on the current line are executed. Multi-level breaks are thus possible by writing 
them all on one line. 

breaksw 

Causes a break from a switch, resuming after the endsw. 
case label: 

A label in a switch statement as discussed below, 
cd 

cd name 
chdir 

chdir name 

Change the shell’s working directory to directory name. If no argument is given then change to 
the home directory of the user. 

If name is not found as a subdirectory of the current directory (and does not begin with V’, ‘./’ or 
then each component of the variable cdpath is checked to see if it has a subdirectory name. 
Finally, if all else fails but ncane is a shell variable whose value begins with V’, then this is tried 
to see if it is a directory. 

continue 

Continue execution of the nearest enclosing while or foreach. The rest of the commands on the 
current line are executed. 

default: 

Labels the default case in a switch statement. The default should come after all case labels. 

dirs 

Prints the directory stack; the top of the stack is at the left, the first directory in the stack being 
the current directory. 

echo wordlist 
echo -n wordlist 

The specified words are written to the shells standard output, separated by spaces, and terminated 
with a newline unless the -n option is specified. 

else 

end 

endif 

endsw 

See the description of the foreach, if, switch, and while statements below, 
eval arg ... 

(As in sh{l).) The arguments are read as input to the shell and the resulting command(s) executed 
in the context of the current shell. This is usually used to execute commands generated as the 
result of command or variable substitution, since parsing occurs before these substitutions. See 
tset(\) for an example of using eval. 
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exec command 

The specified command is executed in pl^e of the current shell, 
exit 

exit(expr) 

The shell exits either with the value of the status variable (first form) or with the value of the 
specified expr (second form). 

fg 

fg %job... 

Brings the current or specified jobs into the foreground, continuing them if they were stopped, 
foreach name (wordlist) 

end 

The variable name is successively set to each member of wordlist and the sequence of commands 
between this command and the matching end are executed. (Both foreach and end must appear 
alone on separate lines.) 

The builtin command continue may be used to continue the loop prematurely and the builtin com¬ 
mand break to toininate it prematurely. When this command is read from the terminal, the loop 
is read up once prompting with *?’ befcwe any statements in the loop are executed. If you make a 
mistake typing in a loop at the terminal you can rub it out 

glob wordlist 

Like echo but no ‘V escapes are recognized and words are delimited by null characters in the out¬ 
put Useful for programs which wish to use the shell to filename expand a list of words. 

goto word 

The specified word is filename and command expanded to yield a string of the form ‘label’. The 
shell rewinds its input as much as possible and searches for a line of the form ‘label:’ possibly 
preceded by blanks or tabs. Execution continues after the specified line. 

hashstat 

Print a statistics line indicating how effective the internal hash table has been at locating com¬ 
mands (and avoiding exec ’s). An exec is attempted for each component of the path where the 
hash function indicates a possible hit, and in each component which does not begin with a ‘/’. 

history 
history n 
history -r n 
history -h n 

Displays the history event list; if n is given only the n most recent events are printed. The -r 
option reverses the order of printout to be most recent first rather than oldest first The -h option 
causes the history list to be printed without leading numbers. This is used to produce files suit¬ 
able for sourceing using the option to source. 

if (expr) command 

If the specified expression evaluates true, then the single command with arguments is executed. 
Variable substitution on command happens early, at the same time it does for the rest of the if 
command. Command must be a simple command, not a pipeline, a command list, or a 
parenthesized command list Input/output redirection occurs even if expr is false, when command 
is not executed (this is a bug). 

if (expr) then 
else if (expr2) then 
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else 

endif 

If the specified eapr is true then the commands to the first else are executed; otherwise if exprl is 
true then the commands to the second else are executed, etc. Any number of else-if pairs are 
possible; only one endif is needed. The else part is likewise option^. (The words else and endif 
must appear at the beginning of input lines; the if must appear alone on its input line or after an 
else.) 

jobs 
jobs -I 

Lists the active jobs; given the -I options lists process id’s in addition to the normal information. 

kill %job 

kill -sig %job ... 

kill pid 

kill -sig pid... 

kiU-1 

Sends either the TERM (terminate) signal or the specified signal to the specified jobs or 
processes. Signals are either given by number or by names (as given in lusr/includelsignal.h, 
stripped of the prefix “SIG”). The signal names are listed by “kill -1”. There is no default, 
saying just ‘kill’ does not send a signal to the current job. If the signal being sent is TERM (ter¬ 
minate) or HUP (hangup), then the job or process will be sent a CONT (continue) signal as well. 

limit 

limit resource 

limit resource maximum-use 
limit -h 

limit -h resource 

limit -h resource maximum-use 

Limits the consumption by the current process and each process it creates to not individually 
exceed maximum-use on the specified resource. If no maximum-use is given, then the current 
limit is printed; if no resource is given, then all limitations are given. If the -h flag is given, the 
hard limits are used instead of the current limits. The hard limits impose a ceiling on the values 
of the current limits. Only the super-user may raise the hard limits, but a user may lower or raise 
the current limits within the legal range. 

Resources controllable currently include cpuiime (the maximum number of cpu-seconds to be 
used by each process), filesize (the largest single file which can be created), datasize (the max¬ 
imum growth of the data-fstack region via sbrk(2) beyond the end of the p-ogram text), stacksize 
(the maximum size of the automatically-extended stack region), and coredumpsize (the size of the 
largest core dump that will be created). 

The maximum-use may be given as a (floating point or integer) number followed by a scale fac¬ 
tor. For all limits other than cputime the default scale is ‘k’ or ‘kilobytes’ (1024 bytes); a scale 
factor of ‘m’ or ‘megabytes’ may also be used. For cputime the default scaling is ‘seconds’, 
while ‘m’ for minutes or ‘h’ for hours, or a time of the form ‘mm:ss’ giving minutes and seconds 
may be used. 

For both resource names and scale factors, unambiguous prefixes of the names suffice. 

login 

Terminate a login shell, replacing it with an instance of /bin/login. This is one way to log off, 
included for compatibility with j/i(l). 
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l(^out 

Terminate a login shell. Especially useful if ignoreeof is set. 

nice 

nice +number 

nice ccHnmand 

nice +number command 

The first form sets the scheduling priority for this shell to 4. The second form sets the priority to 
the given number. The final two forms run command at priority 4 and number respectively. The 
greater the number, the less cpu the process will get. The super-user may specify negative prior¬ 
ity by using ‘nice -number ...’. Command is always executed in a sub-shell, and the restrictions 
placed on commands in simple if statements apply. 

nohup 

nohup command 

The first form can be used in shell scripts to cause hangups to be ignored for the remainder of the 
script. The second form causes the specified command to be run with hangups ignored. All 
processes detached with *&’ are effectively nohup’ed. 

notify 

notify %job ... 

Causes the shell to notify the user asynchronously when the status of the current or specified jobs 
changes; normally notification is presented before a prompt This is automatic if the shell vari¬ 
able notify is set. 

onintr 
onintr - 
onintr label 

Control the action of the shell on interrupts. The first form restores the default action of the shell 
on interrupts which is to terminate shell scripts or to return to the terminal command input level. 
The second form ‘onintr causes all interrupts to be ignored. The final form causes the shell to 
execute a ‘goto label’ when an interrupt is received or a child process terminates because it was 
interrupted. 

In any case, if the shell is running detached and interrupts are being ignored, all forms of onintr 
have no meaning and interrupts continue to be ignored by the shell and all invoked commands. 

popd 
popd +n 

Pops the directory slack, returning to the new top directory. With an argument ‘+n’ discards the 
nth entry in the stack. The elements of the directory stack are numbered fi-om 0 starting at the 
top. 

pushd 
pushd name 
pushd +n 

With no arguments, pushd exchanges the top two elements of the directory stack. Given a name 
argument, pushd changes to the new directory (ala cd) and pushes the old current working direc¬ 
tory (as in csw) onto the directory stack. With a numeric argument, rotates the nth argument of 
the directory stack around to be the top element and changes to it. The members of the directory 
stack are numbered from the top starting at 0. 

rehash 

Causes the internal hash table of the contents of the directories in the path variable to be recom¬ 
puted. This is needed if new commands are added to directories in the path while you are logged 
in. This should only be necessary if you add commands to one of your own directories, or if a 
systems programmer changes the contents of one of the system directories. 
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repeat count command 

The specified command which is subject to the same restrictions as the command in the one line if 
statement above, is executed count times. I/O redirections occur exactly once, even if count is 0. 

set 

set name 
set name=word 
set name[index]-word 
set name=(wordlist) 

The first form of the command shows the value of all shell variables. Variables which have other 
than a single word as value print as a parentl^sized word list. The second form sets name to the 
null string. The third form sets name to the single word. The fourth form sets the index’th com¬ 
ponent of name to word; this component must already exist. The final form sets name to the list 
of words in wordlist. In all cases the value is command and filename expanded. 

These arguments may be repeated to set multiple values in a single set command. Note however, 
that variable expansion happens for all arguments before any setting occurs. 

setenv 

setenv name value 
setenv name 

The first form lists all current environment variables. The last form sets the value of environment 
variable name to be value, a single string. The second form sets name to an empty string. The 
most commonly used environment variable USER, TERM, and PATH are automatically imported 
to and exported from the csh variables user, term, and path; there is no need to use setenv for 
these. 

shift 

shift variable 

The members of argv are shifted to the left, discarding argv[lj. It is an error for argv not to be 
set or to have less than one word as value. The second form performs the same function on the 
specified variable. 

source name 
source -h name 

The shell reads commands from name. Source commands may be nested; if they are nested too 
deeply the shell may run out of file descriptors. An error in a source at any level terminates all 
nested source commands. Normally input during source commands is not placed on the history 
list; the -h option causes the commands to be placed in the history list without being executed. 

stop 

stop %job ... 

Stops the current or specified job which is executing in the background, 
suspend 

Causes the shell to stop in its tracks, much as if it had been sent a stop signal with "Z. This is 
most often used to stop shells started by su(l). 

switch (string) 
case strl: 

breaksw 

default: 

breaksw 
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endsw 

Each case label is successively matched, against the specified string which is first command and 
filename expanded. The file metacharacters **’, *?’ and may be used in the case labels, 
which are variable expanded. If none of the labels match before a ‘default’ label is found, then 
the execution begins iter the default label. Each case label and the default label must appear at 
the beginning of a line. The command breaksw causes execution to continue after the endsw. 
Otherwise control may fall through case labels and default labels as in C. If no label matches 
and there is no default, execution continues after the endsw. 

time 

time command 

With no argument, a summary of time used by this shell and its children is printed. If arguments 
are given the specified simple command is timed and a time summary as described under the time 
variable is printed. If necessary, an extra shell is created to print the time statistic when the com¬ 
mand completes. 

umask 
umask value 

The file creation mask is displayed (first form) or set to the specified value (second form). The 
mask is given in octal. Common values for tte mask are 002 giving all access to the group and 
read and execute access to others or 022 giving all access except no write access for users in the 
group or others. 

unalias pattern 

All aliases whose names match the specified pattern are discarded. Thus all aliases are removed 
by ‘unalias ♦’. It is not an error for nothing to be unaliased. 

unhash 

Use of the internal hash table to speed location of executed programs is disabled, 
unlimit 

unlimit resource 
unlimit -h 
unlimit -h resource 

Removes the limitation on resource. If no resource is specified, then all resource limitations are 
removed. If -h is given, the corresponding hard limits are removed. Only the super-user may do 
this. 

unset pattern 

All variables whose names match the specified pattern are removed. Thus all variables are 
removed by ‘unset this has noticeably distasteful side-effects. It is not an error for nothing to 
be unset. 

unsetenv pattern 

Removes all variables whose name match the specified pattern from the environment. See also 
the setenv command above and printenv(l). 

wait 

All background jobs are waited for. It the shell is interactive, then an interrupt can disrupt the 
wait, at which time the shell prints names and job numbers of all jobs known to be outstanding. 

while (expr) 
end 

While the specified expression evaluates non-zero, the commands between the while and the 
matching end are evaluated. Break and continue may be used to terminate or continue the loop 
prematurely. (The while and end must appear alone on their input lines.) Prompting occurs here 
the first time through the loop as fw theforeach statement if the input is a terminal. 
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%job 

Brings the specified job into the fcseground. 

%job & 

Continues the specified job in the background. 

@ 

@ name ~ expr 
@ name[index] = expr 

The first form prints the values of all the shell variables. The second form sets the specified 
name to the value of expr. If the expression contains *<’, *>’, *&’ or ‘I’ then at least this part of 
the expression must be placed within ‘(* *)’. The third form assigns the value of expr to the 
index’th argument of name. Both name and its index’th component must already exist. 

The operators *♦=’, *+=’, etc are available as in C. The space separating the name from the 
assignment operator is optional. Spaces are, however, mandatory in separating components of 
expr which would otherwise be single words. 

Special postfix *++’ and ‘—’ operators increment and decrement name respectively, i.e. i++’. 
Pre-defined and environment variables 


The following variables have special meaning to the shell. Of these, argv, cwd, home, path, prompt, 
shell and status are always set by the shell. Except for cwd and status this setting occurs only at initial¬ 
ization; these variables will not then be modified unless this is done explicitly by the user. 

This shell copies the environment variable USER into the variable user, TERM into term, and HOME 
into home, and copies these back into the environment whenever the normal shell variables are reset. 
The environment variable PATH is likewise handled; it is not necessary to worry about its setting other 
than in the file .cshrc as inferior csh processes will import the definition of path from the environment, 
and re-export it if you then change it. 


argv 

cdpath 


Set to the arguments to the shell, it is from this variable that positional parameters are 
substituted, i.e. *$1’ is replaced by ‘$argv[l]’, etc. 

Gives a list of alternate directories searched to find subdirectories in chdir commands. 


cwd The full pathname of the current directory. 

echo Set when the -x command line option is given. Causes each command and its argu¬ 

ments to be echoed just before it is executed. For non-builtin commands all expan¬ 
sions occur before echoing. Builtin commands are echoed before command and 
filename substitution, since these substitutions are then done selectively. 

filec Enable file name completion. 

histchars Can be given a string value to change the characters used in history substitution. The 

first character of its value is used as the history substitution character, replacing the 
default character !. The second character of its value replaces the character T in 
quick substitutions. 

history Can be given a numeric value to control the size of the history list Any command 

which has been referenced in this many events will not be discarded. Too large 
values of history may run the shell out of memory. The last executed command is 
always saved on the history list. 

home The home directory of the invoker, initialized from the environment The filename 

expansion of ’ refers to this variable. 
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ignoreeof 

mail 


noclobber 

noglob 

nonomatch 

notify 

path 


prompt 


savehist 


sheU 


status 


time 


If set the shell ignores end-of-file from input devices which are terminals. This 
prevents shells from accidentally being killed by control-D’s. 

The files where the shell checks for mail. This is done after each command comple¬ 
tion which will result in a prompt, if a specified interval has elapsed. The shell says 
‘You have new mail.’ if the file exists with an access time not greater than its modify 
time. 

If the first word of the value of mail is numeric it specifies a different mail checking 
interval, in seconds, than the default, which is 10 minutes. 

If multiple mail files are specified, then the shell says ‘New mail in name' when there 
is mail in the file name. 

As described in the section on Inputloutput, restrictions are placed on output redirec¬ 
tion to insure that files are not accidentily destroyed, and that ‘»’ redirections refer 
to existing files. 

If set, filename expansion is inhibited. This is most useful in shell scripts which are 
not dealing with filenames, or after a list of filenames has been obtained and further 
expansions are not desirable. 

If set, it is not an error for a filename expansion to not match any existing files; 
rather the primitive pattern is returned. It is still an error for the primitive pattern to 
be malformed, i.e. ‘echo [’ still gives an error. 

If set, the shell notifies asynchronously of job completions. The default is to rather 
present job completions just before printing a prompt. 

Each word of the path variable specifies a directory in which commands are to be 
sought for execution. A null word specifies the current directory. If there is no path 
variable then only full padi names will execute. The usual search path is ‘/bin’ 
and ‘/usr/bin’, but this may vary from system to system. For the super-user the 
default search path is ‘/etc’, ‘/bin’ and ‘/usr/bin’. A shell which is given neither the 
-c nor the -t option will normally hash the contents of the directories in the path 
variable after reading .cshrc, and each time the path variable is reset. If new com¬ 
mands are added to these directories while the shell is active, it may be necessary to 
give the rehash or the commands may not be found. 

The string which is printed before each command is read from an interactive terminal 
input If a ‘!’ appears in the string it will be replaced by the current event number 
unless a preceding Y is given. Default is ‘% ’, or ‘# ’ for the super-user. 

is given a numeric value to control the number of entries of the history list that are 
saved in "/.history when the user logs out Any command which has been referenced 
in this many events will be saved. During start up the shell sources "/.history into 
the history list enabling history to be saved across logins. Too large values of 
savehist will slow down the shell during start up. 

The file in which the shell resides. This is used in forking shells to interpret files 
which have execute bits set, but which are not executable by the system. (See the 
description of Non-builtin Command Execution below.) Initialized to the (system- 
dependent) home of the shell. 

The status returned by the last command. If it terminated abnormally, then 0200 is 
added to the status. Builtin commands which fail return exit status ‘1’, all other buil- 
tin commands set status ‘O’. 

Controls automatic timing of commands. If set, then any command which takes more 
than this many cpu seconds will cause a line giving user, system, and real times and a 
utilization percentage which is the ratio of user plus system times to real time to be 
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verbose Set by the -v command line option, causes the words of each command to be printed 

after history substitution. 

Non-builtin command execution 

When a command to be executed is found to not be a builtin command the shell attempts to execute the 
command via execve{2). Each word in the variable path names a directory from which the shell will 
attempt to execute the command. If it is given neither a -c nor a -t option, the shell will hash the 
names in these directories into an internal table so that it will only try an exec in a directory if there is 
a possibility that the command resides there. This greatly spe^ command location when a large 
number of directories are present in the search path. If this mechanism has been turned off (via 
unhash), or if the shell was given a -c or -t argument, and in any case for each directory component of 
path which does not begin with a T, the shell concatenates with the given command name to form a 
path name of a file which it then attempts to execute. 

Parenthesized commands are always executed in a subshell. Thus ‘(cd ; pwd) ; pwd’ prints the home 
directory; leaving you where you were (printing this after the home directory), while ‘cd ; pwd’ leaves 
you in the home directory. Parenthesized commands are most often us^ to prevent chdir from 
affecting the current shell. 

If the file has execute permissions but is not an executable binary to the system, then it is assumed to 
be a file containing shell commands and a new shell is spawned to read it 

If there is an alias for shell then the words of tl» alias will be prepended to the argument list to form 
the shell command. The first word of the alias should be the full path name of the shell (e.g. ‘Sshell’). 
Note that this is a special, late occurring, case of alias substitution, and only allows words to be 
prepended to the argument list without modification. 

Argument list processing 

If argument 0 to the shell is then this is a login shell. The flag arguments are interpreted as follows: 

-b This flag forces a “break” from option processing, causing any further shell arguments to be 
treated as non-option arguments. The remaining arguments will not be interpreted as shell 
options. This may be used to pass options to a shell script without confusion or possible subter¬ 
fuge. The shell will not run a set-user ID script without this option. 

-c Commands are read firom the (single) following argument which must be present Any remaining 
arguments are placed in argv. 

-e The shell exits if any invoked command termin^es abnormally or yields a non-zero exit status. 

-f The shell will start faster, because it will neither search for nor execute commands from the file 
‘.cshrc’ in the invoker’s home directory. 

-i The shell is interactive and prompts for its top-level input even if it appears to not be a terminal. 
Shells are interactive without this option if their inputs and outputs are terminals. 

-n Commands are parsed, but not executed. This aids in syntactic checking of shell scripts. 

-s Command input is taken from the standard input. 

-t A single line of input is read and executed. A ^’ may be used to escape the newline at the end 

of this line and continue onto another line. 

-V Causes the verbose variable to be set, with the effect that command input is echoed after history 
substitution. 

-X Causes the echo variable to be set, so that commands are echoed immediately before execution. 

-V Causes the verbose variable to be set even before ‘.cshrc’ is executed. 

-X Is to -X as -V is to -v. 
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After processing of flag arguments, if arguments remain but none of the -c, -i, -s, or -t options was 
given, the first argument is taken as the name of a file of commands to be executed. The shell opens 
this file, and saves its name for possible resubstitution by ‘$0’. Since many systems use either the stan¬ 
dard version 6 or version 7 shells whose shell scripts are not compatible with this shell, the shell will 
execute such a ‘standard’ shell if the first charact» of a script is not a *#’, i.e. if the script does not 
start with a comment. Remaining arguments initialize the variable argv. 

Signal handling 

The shell normally ignores quit signals. Jobs running detached (either by *&’ or the bg or %... & com¬ 
mands) are immune to signals generated from the keyboard, including hangups. Other signals have the 
values which the shell inherited from its parent The shells handling of interrupts and terminate signals 
in shell scripts can be controlled by onintr. Login shells catch the terminate signal; otherwise this signal 
is passed on to children from the state in the shell’s parent. In no case are interrupts allowed when a 
login shell is reading the file ‘.logout’. 

EUNICE NOTES 

Use *Y, not *Z to suspend jobs for Berkeley job ccmtrol. When you log out all stopped and background 
jobs will be killed. Therefore, it is recommended that you use at(l) to submit background jobs to the 
VMS batch queue. 

Note that redirection always makes a UNIX style file. See unixtovms(l). UNIX style shell scripts, 
created by redirection or brought in from a UNIX site should be run through unixtovms(l). If the csh is 
passed a shell script in UNIX format, it will try to run it like an executable, resulting in an image 
activation error. 

Use suspend to get into a sub-process DCL and ’stopAid=0’ to resume the csh. Note that what you do 
in this sub-process will not effect the current shell. Also control "Y is disabled in the sub DCL process. 

Csh builtin commands piped to more(l), such as "history I more", will result in "stopped tty output". 
The csh puts the command into the background, and more(l) trys to change the terminal modes. This 
is illegal for a background job and currently kills the shell if brought to the foreground. 

If umask is not used in the .login file, files EUNICE BSD creates use the default protection set on the 
VMS level. If you do specify umask in the .login file, files EUNICE BSD creates use the protection 
specified in umask. In addition, VMS delete bits for system, world, group, and user are also set. 

The limit option will not change the stacksize. 

Filename completion is not implemented in EUNICE BSD. 

AUTHOR 

William Joy. Job control and directory stack features first implemented by J.E. Kulp of I.I.A.S.A, Lax- 
enburg, Austria, with different syntax than that used now. File name completion code written by Ken 
Greer, HP Labs. 

FILES 

"/.cshrc 
"/.login 
"/.logout 
/bin/sh 
/tmp/sh* 

/etc/passwd 

LIMITATIONS 

Words can be no longer than 1024 characters. The system limits argument lists to 10240 characters. 
The number of arguments to a command which involves filename expansion is limited to 1/6’th the 
number of characters allowed in an argument list Command substitutions may substitute no more char¬ 
acters than are allowed in an argument list. To detect looping, the shell restricts the number of alias 
substitutions on a single line to 20. 


Read at beginning of execution by each shell. 

Read by login shell, after ‘.cshrc’ at login. 

Read by login shell, at logout. 

Standard shell, for shell scripts not starting with a ‘#’. 
Temporary file for ‘«’. 

Source of home directories for ‘"name’. 
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SEE ALSO 

sh(l), access(2), execve(2), fork(2), killpg(2), pipe(2), sigvec(2), umask(2), setrlimit(2), wait(2), tty(4), 
a.out(5), environ(7), ‘An introduction to the G shell’ 

BUGS 

When a command is restarted from a stop, the shell prints the directory it started in if this is different 
from the current directory; this can be misleading (i.e. wrong) as the job may have changed directories 
internally. 

Shell builtin functions are not stoppableAestartable. Command sequences of the form ‘a ; b ; c’ are 
also not handled gracefully when stopping is attempted. If you suspend ‘b’, the shell will then immedi¬ 
ately execute ‘c*. This is especially noticeable if this expansion results from an alias. It suffices to 
place the sequence of commands in O’s to force it to a subshell, i.e. ‘(a ; b ; c )’. 

Control over tty output after processes are started is primitive; perhaps this will inspire someone to 
work on a good virtual terminal interface. In a virtual terminal interface much more interesting things 
could be done with output control. 

Alias substitution is most often used to clumsily simulate shell procedures; shell procedures should be 
provided rather than aliases. 

Commands within loops, prompted for by *?*, are not placed in the history list. Control structure 
should be parsed rather than being recognized as built-in commands. This would allow control com¬ 
mands to be placed anywhere, to be combined with ‘I*, and to be used with *&’ and metasyntax. 

It should be possible to use the modifiers on the output of command substitutions. All and more 
than one modifier should be allowed on *$’ substitutions. 

The way the filec facility is implemented is ugly and expensive. 
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NAME 

ctags - create a tags file 
SYNOPSIS 

Ctags [ -BFatuwvx ] [ -f tagsfile ] name ... 

DESCRIPTION 

Ctags makes a tags file for ex(l) firom the specified C, Pascal, Fortran, YACC, lex, and lisp sources. A 
tags file gives the locations of specified objects (in this case functions and typedefs) in a group of files. 
Each line of the tags file contains the object name, the file in which it is defined, and an address 
specification for the object definition. Functions are searched with a pattern, typedefs with a line 
number. Specifiers are given in separate fields on the line, separated by blanks or tabs. Using the tags 
file, ex can quickly find these objects definitions. 

If the -X flag is given, ctags produces a list of object names, the line number and file name on which 
each is defined, as well as the text of that line and prints this on the standard ouq}ut This is a simple 
index which can be printed out as an off-line readable function index. 

If the -v flag is given, an index of the form expected by vgrind(l) is produced on the standard output. 
This listing contains the function name, file name, and page number (assuming 64 line pages). Since 
the ouq)ut will be sorted into lexicographic order, it may be desired to run the output through sort -f. 
Sample use: 

ctags -V files I sort -f > index 
vgrind -x index 

Normally ctags places the tag descriptions in a file called tags; this may be overridden with the -f 
option. 

Files whose names end in .c or .h are assumed to be C source files and are searched for C routine and 
macro definitions. Files whose names end in .y are assumed to be YACC source files. Files whose 
names end in J are assumed to be either lisp files if their first non-blank character is or ‘[’, or 

lex files otherwise. Other files are first examined to see if they contain any Pascal or Fortran routine 
definitions; if not, they are processed again looking for C definitions. 

Other options are: 

-F use forward searching patterns (J..J) (default). 

-B use backward searching patterns (?...?). 

-a append to tags file. 

“t create tags for typedefs. 

-w suppressing warning diagnostics. 

-u causing the specified files to be updated in tags, that is, all references to them are deleted, and the 
new values are appended to the file. (Beware: this option is implemented in a way which is 
rather slow; it is usually faster to simply rebuild the tags file.) 

The tag main is treated specially in C programs. The tag formed is created by prepending M to the 
name of the file, with a trailing .c removed, if any, and leading pathname components also removed. 
This makes use of ctags practical in directories with more than one program. 

FILES 

tags output tags file 

SEE ALSO 

ex(l), vi(l) 

AUTHOR 

Ken Arnold; FORTRAN added by Jim Kleckner, Bill Joy added Pascal and -x, replacing cxref; C 
typedefs added by Ed Pelegri-LloparL 
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BUGS 

Recognition of functions, subroutines and procedures for FORTRAN and Pascal is done is a very 
simpleminded way. No attempt is made to deal with block structure; if you have two Pascal procedures 
in different blocks with the same name you lose. 

The method of deciding whether to look for C or Pascal and FORTRAN functions is a hack. 

Does not know about #ifdefs. 

Should know about Pascal types. Relies on the input being well formed to detect typedefs. Use of -tx 
shows only the last line of typedefs. 
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NAME 

cvtbackup - procedure to convert between VMS backup form^ and UNIX format 
SYNOPSIS 

cvtbackup [-pack/-unpack] saveset packedsaveset 
DESCRIPTION 

pack: Turns a save set into fixed length 512-byte records, 
unpack: Turns fixed length 512 byte records back into a save set. 

Cvtbackup is a utility program that packs or unpacks a VMS backup save set into a form that is more 
easily transported between machines (typically over networks and non-ANSI tape formats). A typical 
use, such as sending a backup save set over a UUCP link, comprises these steps: 

1. A backup file is created on disk, with BLOCK^2048/GROUP=0 to keep the size down 

2. cvtbackup is run to create a UNIX file 

3. The UNIX file is run through uuencode to make it all ASCII. 

4. The resulting file is transported ovw the network and run through uudecode to turn it 
back into binary. 

5. cvtbackup is again run to unpack the file into a backup save set 

6. The save set is restored using backup. 

FILES 

/usr/eun/cvtbackup 
EUNICE NOTES 

cvtbackup is a EUNICE BSD-specific command. 
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NAME 

cvtfnames - convert hashed file names 
SYNOPSIS 

cvtfnames [ option ] filename ... 

DESCRIPTION 

Cvtfnames will convert filenames which were hashed by versions previous to EUNICE BSD Version 
4.1. The name will be re-hashed to a new name. With VMS 4.0 the RMS file system was modified to 
allow a greater range in filenames. The hashing algorithm uses a single file, rathw than the older 
method of two files, one name HSHxxxxxx.HSN and the other either HSHxxxxxx.HSH or 
HSHxxxxxx.DIR (depending whether the file was a directory or not). 

Filenames which were hashed because of either name or extension length, such as .login will no longer 
be hashed. A dollar sign will be used to indicate a change of case. For instance, the filename, 
Makefile, will hashed to $M$AKEFILE. 

Cvtfnames will prompt before changing each old hashed file. Respond y or <CR> for the filename to 
be changed. 

-f can be used to force the change to be made for all files specified. To force a change on all 
files in the current directory and below, use: cvtfhames -f *[...]* 

EUNICE NOTES 

This utility was created for EUNICE BSD Version 4.1. 

BUGS 

A corrupted HSHxxxxxx.HSN file (e.g. zero length) will cause a "cannot read UNIX filename" message. 
Each subsequent conversion attempt then fails with a "cannot stat HSHxxxxxx.HSN" file. Delete the 
corrupted hashed file first and then rerun cvtfnames, 

(Note: Doing an in EUNICE will often show a "HSH" file when this situation occurs.) 
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NAME 

date - print and set the date 
SYNOPSIS 

date [ -n ] [ -u ] [ yymmddhhmm [ ^s ] ] 

DESCRIPTION 

If no arguments are given, the current date and time are printed. Providing an argument will set the 
desired date. Only the superus^ can set the date. The -u flag is used to display or set the date in GMT 
(univCTsal) time, yy represents the last two digits of the year, the first mm is the month number; dd is 
the day number, hh is the hour numba* (24 lK)ur system); the second mm is the minute number; »ss is 
optional and represents the seconds. For example: 

date 8506131627 

sets the date to June 13 1985, 4:27 PM. The year, month and day may be omitted; the default values 
will be the current ones. The system operates in GMT. Date takes care of the conversion to and from 
local standard and daylight-saving time. 

If timed(8) is running to synchronize the clocks of machines in a local area network, date sets the time 
globally on all those machines unless the -n option is given. 

FILES 

/usr/adm/wtmp to record time-setting. In /usr/adm/messages, date records the name of the user setting 
the time. 

SEE ALSO 

gettimeofday(2), utmp(5), timed(8), 

TSP: The Time Synchronization Protocol for UNIX 4.3BSD, R. Gusella and S. Zatti 
DIAGNOSTICS 

Exit status is 0 on success, 1 on complete failure to set the date, and 2 on successfully setting the local 
date but failing globally. 

‘You are not superuser: date not set’ if you try to change the date but are not the super-user. Occasion¬ 
ally, when timed synchronizes the time on many hosts, the setting of a new time value may require 
more than a few seconds. On these occasions, date prints: ‘Network time being set’. The message 
‘Communication oror with timed’ occurs when the communication between date and timed fails. 

BUGS 

The system attempts to keep the date in a format closely compatible with VMS. VMS, however, uses 
local time (rather than GMT) and does not understand daylight-saving time. Thus, if you use both 
UNIX and “^^S, VMS will be running on GMT. 
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NAME 

dbx - debugger 
SYNOPSIS 

dbx [ -r ] [ -i ] [ -k ] [ -I dir ] [ -c file ] [ objfile [ coredump ]] 

DESCRIPTION 

Dbx is a tool for source level debugging and execution of programs under UNIX. The objfile is an 
object file produced by a ccxnpiler with the appropriate flag (usually “-g”) specified to produce symbol 
information in the object file. Currently, cc(l), j77(l), pc(l), and the DEC Western Research Labora¬ 
tory Modula-2 compiler, mod(l), produce the appropriate source information. The machine level facili¬ 
ties of dbx can be used on any program. 

The object file contains a symbol table that includes the name of the all the source files translated by 
the compiler to create it. These files are available for perusal while using the debugger. 

If a file named “core” exists in the current directory or a coredump file is specified, dbx can be used to 
examine the state of the program when it faulted. 

If the file “.dbxinit” exists in the current directory then the debugger commands in it are executed. 
Dbx also checks for a “.dbxinit” in the usot’s home directory if there isn’t one in the current directory. 

The command line options and their meanings are: 

-r Execute objjile immediately. If it terminates successfully dbx exits. Otherwise the reason for 
terminati(»i will be reported and the user off»^ the option of entering the debugger or letting 
the program fault Dbx will read from “/dev/tty” when -r is specified and standard input is 
not a terminal. 

-i Force dbx to act as though standard input is a terminal. 

-k Map memory addresses, useful for kernel debugging. 

-I dir Add dir to the list of directories that arc searched when looking for a source file. Normally 
dbx looks for source files in the current directory and in the directory where objfile is located. 
The directory search path can also be set with the use command. 

-cfile Execute the dbx commands in the file before reading from standard input. 

Unless -r is specified, dbx just prompts and waits for a command. 

Execution and Tracing Commands 

run [args] [< filename] [> filename] 
rerun [args] [< filename] [> filename] 

Start executing objfile, passing args as command line arguments; < or > can be used to redirect 
input or output in the usual manner. When rerun is used without any arguments the previous 
argument list is passed to the program; otherwise it is identical to run. If objfile has been 
written since the last time the symbolic information was read in, dbx will read in the new 
information. 

trace [in procedure/function] [if condition] 
trace source-line-number [if condition] 
trace procedurelfunction [in procedure/function] [if condition] 
trace expression at source-line-number [if condition] 
trace variable [in procedurelfunction] [if condition] 
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Have tracing information printed when the program is executed. A number is associated with 
the command that is used to turn the tracing off (see the delete command). 

The first argument describes what is to be traced. If it is a source-line-number, then the line is 
printed immediately prior to being executed. Source line numbers in a file other than the 
current one must be preceded by the name of the file in quotes and a colon, e.g. 
"mumble.p":17. 

If the argum^t is a procedure or function name then every time it is called, information is 
printed telling what routine called it, from what source line it was called, and what parameters 
were passed to it In addition, its return is noted, and if it’s a function then the value it is 
returning is also printed. 

If the argument is an expression with an at clause then the value of the expression is printed 
whenever the identified source line is reached. 

If the argument is a variable then the name and value of the variable is printed whenever it 
changes. Execution is substantially slower during this form of tracing. 

If no argument is specified then all source lines are printed before they are executed. Execu¬ 
tion is substantially slower during this fmm of tracing. 

The clause “in procedurelfunction" restricts tracing information to be printed only while exe¬ 
cuting inside the given procedure or function. 

Condition is a boolean expression and is evaluated prior to printing the tracing information; if 
it is false then the information is not printed. 

stop if condition 

stop at source-line-number [if condition] 
stop in procedweffunction [if condition] 
stop variable [if condition] 

Stop execution when the given line is reached, procedure or function called, variable changed, 
or condition true. 

status [> filename] 

Print out the currently active trace and stop commands, 
delete command-number ... 

The traces or stops corresponding to the given numbers are removed. The numbers associated 
with traces and stops are printed by the status command. 

catch number 
catch signal-name 
ignore number 
ignore signal-name 

Start or stop trapping a signal before it is sent to the program. This is useful when a program 
being debugged handles signals such as intorupts. A signal may be specified by number or by 
a name (e.g., SIGINT). Signal names are case insensitive and the “SIG’’ prefix is optional. 
By default all signals are trapped except SIGCONT, SIGCHILD, SIGALRM and SIGOLL. 

cont integer 
cont signal-name 

Continue execution from where it stopped. If a signal is specified, the process continues as 
though it received the signal. Otherwise, the process is continued as though it had not been 
stopped. 
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Execution cannot be continued if the process has “finished”, that is, called the standard procedure 
“exit”. Dbx does not allow the process to exit, thereby letting the user to examine the program state. 

step Execute one source line. 

next Execute up to the next source line. The difference between this and step is that if the line 
contains a call to a procedure or function the step command will stop at the beginning of that 
block, while the next command will not 

return [procedure] 

Continue until a return to procedure is executed, or until the current procedure returns if none 
is specified. 

call procedure(parameters) 

Execute the object code associated with the named p'ocedure or function. 

Printing Variables and Expressions 


Names are resolved first using the static scope of the current function, then using the dynamic scope if 
the name is not defined in the static scope. If static and dynamic searches do not yield a result, an arbi¬ 
trary symbol is chosen and the message “[using qualified nameV* is printed. The name resolution pro¬ 
cedure may be overridden by qualifying an identifier with a block name, e.g., '"module.variable”. For 
C, source files are treated as modules named by the file name without “.c”. 

Expressions are specified with an approximately common subset of C and Pascal (or equivalently 
Modula-2) syntax. Indirection can be denoted using either a prefix or a postfix and array 
expressions are subscripted by brackets (“[ ]”). The field reference operator (“.”) can be used with 
pointed as well as records, making the C operator “->” unnecessary (although it is supported). 

Types of expressions are chedked; the type of an expression may be ovaridden by using "type- 
nameiexpression)”. When there is no corresponding named type the special constructs ”&type-name” 
and ”$$tag-name” can be used to represent a pointer to a named type or C structure tag. 


assign variable = expression 

Assign the value of the expression to the variable. 

dump [procedure] [> filename] 

Print the names and values of variables in the given procedure, or the current one if none is 
specified. If the procedure given is “.”, then the all active variables are dumped. 

print expression [, expression ..,] 

Print out the values of the expressions. 

whatis name 

Print the declaration of the given name, which may be qualified with block names as above, 
which identifier 

Print the full qualification of the given identifer, i.e. the outer blocks that the identifier is asso¬ 
ciated with. 

up [count] 
down [count] 

Move the current function, which is used for resolving names, up or down the stack count lev¬ 
els. The default count is 1. 

where Print out a list of the active procedures and function, 
whereis ideruifier 

Print the full qualification of all the symbols whose name matches the given identifier. The 
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order in which the symbols are printed is not meaningful. 

Accessing Source Files 

Iregidar expressionl/] 

^regular exprmwn[?] 

Search forward or backward in the current source file for the given pattern, 
edit [filename] 

edit procedurelfunction-name 

Invoke an editor on filename or the current source file if none is specified. If a procedure or 
function name is specified, the editor is invoked on the file that contains it Which editor is 
invoked by default depends on the installation. The default can be overridden by setting the 
environment variable EDITOR to the name of the desired editor. 

file [filename] 

Change the current source file name to filename. If none is specified then the current source 
file name is printed. 

func [procedureffunction] 

Change the current function. If none is specified then print the current function. Changing the 
current function implicitly changes tl^ current source file to the one that contains the function; 
it also changes the curr^t scope used for name resolution. 

list [source-line-number [, source-line-number]] 
list procedureffunction 

List the lines in the current source file firom the first line number to the second inclusive. If no 
lines are specified, the next 10 lines are listed. If the name of a procedure or function is given 
lines n-k to n+it are listed where n is the first statement in the procedure or function and k is 
small. 

use directory-list 

Set the list of directories to be searched when looking for source files. 

Command Aliases and Variables 

alias name name 

alias name **string” 

alias name (parameters) ”string” 

When commands are processed, dbx first checks to see if the word is an alias for either a com¬ 
mand or a string. If it is an alias, then dbx treats the input as though the corresponding string 
(with values substituted for any parameters) had been entered. For example, to define an alias 
“rr” for the command “rerun”, one can say 

alias rr rerun 

To define an alias called “b” that sets a stop at a particular line one can say 
alias b(x) “stop at x” 

Subsequently, the command “b(12)” will expand to “stop at 12”. 
set imme [- expression] 

The set command defines values for debugger variables. The names of these variables cannot 
conflict with names in the program being debugged, and are expanded to the corresponding 
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expression within other commands. The following variables have a special meaning: 

$firame 

Setting this variable to an ^dress causes dbx to use the stack frame pointed to by the 
address for doing stack traces and accessing local variables. This facility is of partic¬ 
ular use for kernel debugging. 

Shexchars 

Shexints 

Shexoffsets 

Shexstrings 

When set, dbx prints out out characters, integers, offsets from registers, or character 
pointers respectively in hexadecimal. 

Slistwindow 

The value of this variable specifies the number of lines to list around a function or 
when the list command is given without any parameters. Its default value is 10. 

$mapaddrs 

Setting (unsetting) this variable causes dbx to start (stop) mapping addresses. As 
with “Sfirame”, this is useful for konel debugging. 

Sunsafecall 

Sunsafeassign 

When “Sunsafecall” is set, strict type checking is turned off for arguments to sub¬ 
routine or function calls (e.g. in the call statement). When “Sunsafeassign” is set, 
strict type checking between the two sides of an assign statement is turned off. 
These variables should be used only with great care, because they severely limit 
dbx’s usefulness for detecting orors. 

unalias name 

Remove the alias with the given name, 
unset name 

Delete the debugger variable associated with name. 

Machine Level Commands 

trace! [address] [if cond] 
trace! [variable] [at address] [if cond] 
stop! [address] [if cond] 
stop! [at] [address] [if cond] 

Turn on tracing or set a stop using a machine instruction address. 

step! 

next! Single step as in step or next, but do a single instruction rather than source line. 

address ^addressl [mode] 
address / [count] [mode] 

Print the contents of memory starting at the first address and continuing up to the second 
address or until count items are printed. If the address is the address following the one 
printed most recently is used. The mode specifies how memory is to be printed; if it is omitted 
the previous mode specified is used. The initial mode is “X”. The following modes are sup¬ 
ported: 
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i print the machine instruction 

d print a short word in decimal 

D print a long word in decimal 

o print a short word in octal 

O print a long word in octal 

X print a short word in hexadecimal 

X print a long word in hexadecimal 

b print a byte in octal 

c print a byte as a character 

s print a string of characters terminated by a null byte 
f print a single precision real number 
g print a double precision real number 

Symbolic addresses are specified by preceding the name with an Registers are denoted by 

“$rN” where N is the number of the register. Addresses may be expressions made up of other 
addresses and the operators and indirection (unary 

Miscellaneous Commands 

gripe Invoke a mail program to send a message to the person in charge of dbx. 
help Print out a synopsis of dbx commands, 

quit Exit dbx. 

sh command-line 

Pass the command line to the shell for execution. The SHELL environment variable deter¬ 
mines which shell is used. 

source filename 

Read dbx commands from the given filename. 

FILES 

a.out object file 

.dbxinit initial commands 

SEE ALSO 

cc(l). f77(l), pc(l). mod(l) 

COMMENTS 

Dbx suff(^ from the same “multiple include” malady as did sdb. If you have a program consisting of 
a numb^ of object files and each is built from source files that include heado* files, the symbolic infor¬ 
mation for the header files is replicated in each object file. Since about one debugger start-up is done 
for each link, having the linker (Id) re-organize the symbol information would not save much time, 
though it would reduce some of the disk space used. 

This problem is an artifact of the unrestricted semantics of #include’s in C; for example an include file 
can contain static declarations that are separate entities for each file in which they are included. How¬ 
ever, even with Modula-2 there is a substantial amount of duplication of symbol information necessary 
for inter-module type checking. 

Some problems remain with the support for individual languages. Fortran problems include: inability 
to assign to logical, logical*2, complex and double complex variables; inability to represent parameter 
constants which are not type integer or real; peculiar representation for the values of dummy procedures 
(the value shown for a dummy procedure is actually the first few bytes of the procedure text; to find the 
location of the procedure, use “&” to take the address of the variable). 
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NAME 

dc - desk calculator 

SYNOPSIS 

dc [ file ] 

DESCRIPTION 

Dc is an arbitrary precision arithmetic package. Ordinarily it operates on decimal integers, but one may 
specify an input base, output base, and a number of fractional digits to be maintained. The overall 
structure of dc is a stacking (reverse Polish) calculator. If an argument is given, input is taken from 
that file until its end, then fix)m the standard input The following constructions are recognized: 

number 

The value of the number is pushed on the stack. A number is an unbroken string of the digits 
0-9. It may be preceded by an undersc(»% _ to input a negative number. Numbers may contain 
decimal points. 

+ -/*%" 

The top two values on the stack are added (+), subtracted (-), multiplied (*), divided ij), remain¬ 
dered (%), or exponentiated ('). The two entries are popped off the stack; the result is pushed 
on the stack in their place. Any fractional part of an exponent is ignored. 

sx The top of the stack is popped and stored into a register named x, where x may be any charac¬ 
ter. If the s is capitalized, x is treated as a stack and the value is pushed on it. 

lx The value in register x is pushed on the stack. The register x is not altered. All registers start 
with zero value. If the 1 is capitalized, register x is treated as a stack and its top value is popped 
onto the main stack. 

d The top value on the stack is duplicated. 

p The top value on the stack is printed. The top value remains unchanged. P interprets the top of 

the stack as an ascii string, removes it, and prints it. 

f All values on the stack and in registers are printed. 

q exits the program. If executing a string, the recursion level is popped by two. If q is capital¬ 
ized, the top value on the stack is popped and the string execution level is popped by that value. 

X treats the top element of the stack as a character string and executes it as a string of dc com¬ 
mands. 

X replaces the number on the top of the stack with its scale factor. 

[... ] puts the bracketed ascii string onto the top of the stack. 

<x >x =x 

The top two elements of the stack are popped and compared. Register x is executed if they 
obey the stated relation. 

v replaces the top element on the stack by its square root. Any existing fractional part of the 
argument is taken into account, but otherwise the scale factor is ignored. 

! interprets the rest of the line as a UNIX command. 

c All values on the stack are popped. 

i The top value on the stack is popped and used as the number radix for further input. I pushes 
the input base on the top of the stack. 

0 The top value on the stack is popped and used as the number radix for further output. 

O pushes the output base on the top of the stack. 

k the top of the stack is popped, and that value is used as a non-negative scale factor: the 

appropriate number of places are printed on output, and maintained during multiplication, 
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division, and exponentiation. The interaction of scale factor, input base, and output base will be 
reasonable if all are changed together. 

z The stack level is pushed onto the stack. 

Z replaces the number on the top of the stack with its length. 

? A line of input is taken from the input source (usually the terminal) and executed. 

;: are used by be for array op^tions. 

An example which prints the first ten values of n! is 

[lal+dsa*plalO>y]sy 

Osal 

lyx 

SEE ALSO 

bc(l), which is a preprocessor for dc providing infix notation and a C-like syntax which implements 
functions and reasonable control structures for programs. 

DIAGNOSTICS 

‘x is unimplemented* where x is an octal number. 

’stack empty’ for not enough elements on the stack to do what was asked. 

‘Out of space’ when the free list is exhausted (too many digits). 

‘Out of headers’ for too many numbers being kept around. 

‘Out of pushdown’ for too many items on the stack. 

‘Nesting Depth’ for too many levels of nested execution. 
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NAME 

dd - convert and copy a file 

SYNOPSIS 

dd [option=value] ... 


DESCRIPTION 

Dd copies the specified input file to the specified output with possible conversions. The standard input 
and output are used by default. The input and output block size may be specified to take advantage of 
raw physical I/O. 


option 

if= 

Ofss 

ibs=n 

obs=n 

bS“/i 

cbs=sn 

skipsn 

files=n 


seek=srt 

count-n 

convsascii 

ebcdic 

ibm 

block 

unblock 

lease 

ucase 

swab 

noerror 

sync 


values 

input file name; standard input is default 
output file name; standard output is default 
input block size n bytes (default 512) 
output block size (default 512) 

set both input and output block size, superseding ibs and obs; also, if no conversion is 

specified, it is particularly efficient since no cq)y need be done 

conversion buffer size 

skip n input records before starting copy 

copy n input files before terminating (makes sense only where input is a magtape or 
similar device). 

seek n records from beginning of output file before copying 

copy only n input records 

convert EBCDIC to ASCII 

convert ASCII to EBCDIC 

slightly different map of ASCII to EBCDIC 

convert variable length records to fixed length 

convert fixed length records to variable length 

mt^ alphabetics to lower case 

map alphabetics to upper case 

swap every pair of bytes 

do not stop processing on an error 

pad every input record to ibs 

several comma-separated conversions 


Where sizes are specified, a number of bytes is expected. A number may end with k, b or w to specify 
multiplication by 1024, 512, or 2 respectively; a pair of numbers may be separated by x to indicate a 
product 

Cbs is used only if ascii, unblock, ebcdic, ibm, or block convCTsion is specified. In the first two cases, 
ebs characters are placed into the conversion buffer, any specified character mapping is done, trailing 
blanks trimmed and new-line added before sending the line to the output. In the latter three cases, 
characters are read into the conversion buffer, and blanks added to make up an output record of size 
cbs. 


After completion, dd reports the number of whole and partial input and output blocks. 

For example, to read an EBCDIC tape blocked ten 80-byte EBCDIC card images per record into the 
ASCII file x; 


dd if=:/dev/rmtO of=x ibs=800 cbs=80 conv=ascii,lcase 

Note the u^ of raw magtape. Dd is especially suited to I/O on the raw physical devices because it 
allows reading and writing in arbitrary record sizes. 
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EUNICE NOTES 

EUNICE dd(l) requires that the tape drive is mounted foreign with the appropriate blocksize. The 
blocksize is determined by the VMS mount command, never automatically. For a blocking factor of 20 
(a very popular quantity) mount with a blocksize of 10240. For example, for tape drive MTAO:, mount 
with the following command: 

$ MOUNT/FOREIGN/BL<X:KSIZE=10240 MTAO: 

The only valid blocksize for the VMS file system on the disk is 512. Therefore, dd will always create 
blocks of 512. However, dd will be able to read files firom a t 2 ^ which were created with a different 
blocksize. For example, if the tape was created with blocks of 5120, mount as follows: 

S MOUNT/FOREIGN/BLOCKSIZE=5120 MTAO: 

Ento* the EUNICE environment, and type the following to read the tape: 

% dd if=/dev/rmtO of=readfile ibs=5120 obs=512 

With VMS versions prior to 4.2, do not use the suspend or vms(l) commands to mount the tape, rather 
mount from the DCL level. Starting with VMS 4.2, tapes can be mounted by a subprocess using either 
suspend or vms(l). 

SEE ALSO 

cp(l), tr(l) 

DIAGNOSTICS 

f+p records in(out): numbers of full and partial records read(written) 

BUGS 

The ASCII/EBCDIC conversion tables are taken from the 256 character standard in the CACM Nov, 
1968. The ‘ibm* conversion, while less blessed as a standard, corresponds better to certain IBM print 
train conventions. There is no universal solution. 

One must specify “conv=noerror,sync” when copying raw disks with bad sectors to insure dd stays 
synchronized. 

Certain combinations of arguments to conv^ are permitted. However, the block or unblock option can¬ 
not be combined with ascii, ebcdic or ibm. Invalid combinations silently ignore all but the last 
mutually-exclusive keywwd. 
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NAME 

deroff - remove nroff, troff, tbl and eqn constructs 

SYNOPSIS 

deroff [ -w ] file ... 

DESCRIPTION 

Deroff reads each file in sequence and removes all nroff and troff command lines, backslash construc¬ 
tions, macro definitions, eqn constructs (between ‘JEQ’ and ‘£N’ lines or between delimiters), and table 
descriptions and writes the remaindo* on the standard output Deroff follows chains of included files 
(‘.so’ and ‘.nx’ commands); if a file has already been included, a ‘.so’ is ignored and a ‘.nx’ terminates 
execution. If no input file is given, deroff reads from the standard input file. 

If the -w flag is given, the output is a word list, one ‘word’ (string of letters, digits, and apostrophes, 
beginning with a letter, apostrophes are removed) per line, and all other characters ignored. Otherwise, 
the output follows the original, with the deletions mentioned above. 

SEE ALSO 

troff(l), eqn(l), tbl(l) 

BUGS 

Deroff is not a complete troff interpreter, so it can be confused by subtle constructs. Most errors result 
in too much rather than too little output 
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NAME 

df - disk free 
SYNOPSIS 

df [ -i ] [ filesystem ... ] [ file ... ] 

DESCRIPTION 

D/prints out the amount of free disk space available on the specified filesystem, e.g. “/dev/rpOa”, or on 
the filesystem in which the specified file, e.g. **$HOME”, is contained. If no file system is specified, 
the free space on all of the normally mounted file systems is printed. The reported numbers are in kilo¬ 
bytes. 

Other options are: 

-i Report also the number of inodes which are used and free. 

FILES 

/etc/fstab list of normally mounted filesystems 

SEE ALSO 

fstab(5) 
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NAME 

diction, explain - print wordy sentences; thesaurus for diction 
SYNOPSIS 

diction [ -ml ] [ -mm ] [ -n ] [ -f pfile ] file ... 
explain 

DESCRIPTION 

Diction finds all sentences in a document that contain phrases from a data base of bad or wordy diction. 
Each phrase is bracketed with [ ]. Because diction runs deroffhefore looking at the text, formatting 
header files slu)uld be included as part of the input The default macro package -ms may be overridden 
with the flag -mm. The flag -ml which causes deroff to skip lists, should be used if the document con¬ 
tains many lists of non-sentences. The user may supply her/his own pattern file to be used in addition 
to the default file with -f pfile. If the flag -n is also supplied the default file will be suppressed. 

Explcdn is an interactive thesaurus for the phrases found by diction. 

SEE ALSO 

deroff(l) 

BUGS 

Use of non-standard formatting macros may cause incorrect sentence breaks. In particular, diction 
doesn’t grok nne. 
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NAME 

diff - differential file and directory comparator 
SYNOPSIS 

diff [ -1 ] [ -r ] [ -s ] [ -cefhn ] [ -biwt ] dirl dir2 
diff [ -cefhn ] [ -biwt ] filel file2 
diff [ -Dstring ] [ -biw ] filel file2 

DESCRIPTION 

If both argum^ts are directories, diff sorts the contents of the directories by name, and then runs the 
regular file diff algorithm (described below) on text files which are different Binary files which differ, 
common subdirectories, and files which appear in only one directory are listed. Options when compar¬ 
ing directories are: 

-1 long ou4)ut format; each text file diff is piped through pr{l) to paginate it, other differences are 
remembo^d and summarized after all text file differences are reported. 

-r causes application of recursively to common subdirectories encountered. 

-s causes dff to report files which are the same, which are otherwise not mentioned. 

-Sname 

starts a directory dff in the middle beginning with file name. 

When run on regular files, and when comparing text files which differ during directory comparison, diff 
tells what lines must be changed in the files te bring them into agreement. Except in rare cir¬ 
cumstances, diff finds a smallest sufficient set of file differences. If neither filel nor filel is a directory, 
then either may be given as in which case the standard input is used. If filel is a directory, then a 
file in that directory whose file-name is the same as the file-name of filel is used (and vice versa). 

There are several options for output format; the default output format contains lines of these forms: 

nl a nSM 
nlji2 d n3 
nl,nl c n3,n4 

These lines resemble ed commands to convert filel into filel . The numbers after the letters pertain to 
filel . In fact, by exchanging ‘a’ for ‘d* and reading backward one may ascertain equally how to con¬ 
vert filel into filel . As in ed, identical pairs where nl - n2 ox n3 - n4 are abbreviated as a single 
number. 

Following each of these lines come all the lines that are affected in the first file flagged by *<’, then all 
the lines that are affected in the second file flagged by ’>’. 

Except for -b, -w, -i or -t which may be given with any of the others, the following options are mutu¬ 
ally exclusive: 

-e produces a script of a, c and d commands for the editor ed, which will recreate filel from 

filel . In connection with -e, the following shell program may help maintain multiple ver¬ 
sions of a file. Only an ancestral file ($1) and a chain of version-to-version ed scripts 
($2,$3,...) made by dijlf need be on hand. A ‘latest version’ appears on the standard output. 

(shift; cat $♦; echo 'USp^ | ed - $1 

Extra commands are added to the output when comparing directories with -e, so that the 
result is a sh{l) script for converting text files which are common to the two directories from 
their state in cUrl to their state in dirl. 

-f produces a script similar to that of -e, not useful with ed, and in the opposite order. 

-n produces a script similar to that of -e, but in the opposite order and with a count of changed 

lines on each insert or delete command. This is the form used by rcsdiff(l). 

-c produces a diff with lines of context The default is to present 3 lines of context and may be 
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changed, e.g to 10, by -clO. With -c the output format is modified slightly: the output 
beginning with identification of the files involved and their creation dates and then each 
change is separated by a line with a dozen ♦’s. The lines removed from filel are marked 
with those added to file2 are marked ‘+ Lines which are changed from one file to the 
other are marked in both files with with ‘! 

Changes which lie within <context> lines of each other are grouped together on output. 
(This is a change from the previous “diff -c” but the resulting output is usually much easier 
to interpret) 

-h does a fast, half-hearted job. It works only when changed stretches are short and well 
separated, but does work on files of unlimited length. 

-Dstring causes diff to create a merged version of filel and filel on the standard output, with C 
preprocessor controls included so that a compilation of the result without defining string is 
equivalent to compiling while defining string will yield filel. 

-b causes trailing blanks (spaces and tabs) to be ignored, and other strings of blanks to compare 
equal. 

-w is similar to -b but causes whitespace (blanks and tabs) to be totally ignored. E.g., 
“if ( a = b )” will compare equal to “if(a=b)”. 

-i ignores the case of letters. E.g., “A” will compare equal to “a”. 

-t will expand tabs in output lines. Normal or -c output adds character(s) to the front of each 

line which may screw up the indentation of the original source lines and make the output 
listing difficult to interpret This option will preserve the original source’s indentation. 

FILES 

/tmp/d????? 

/usr/lib/diffh for -h 

/bin/diff for directory diffs 

/bin^r 

SEE ALSO 

cmp(l), cc(l), comm(l), ed(l), dif£3(l) 

DIAGNOSTICS 

Exit status is 0 for no differences, 1 for some, 2 for trouble. 

BUGS 

^ting scripts produced under the -e or -f option are naive about creating lines consisting of a single 


When comparing directories with the -b, -w or -i options specified, diff first compares the files ala cmp, 
and then decides to run the diff algorithm if they are not equal. This may cause a small amount of 
spurious output if the files then turn out to be identical because the only differences are insignificant 
blank string or case differences. 
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NAME 

diff3 - 3-way differential file comparison 
SYNOPSIS 

diff3 [ -exEX3 ] filel file2 fileS 
DESCRIPTION 

Dijf3 compares three versions of a file, and publishes disagreeing ranges of text flagged with these 
codes: 

=== all three files differ 

==1 filel is different 

==2 filel is different 

=s=3 files is different 

The type of change suffered in converting a given range of a given file to some other is indicated in 
one of these ways: 

/: ni a Text is to be appended after line number nl in file f, where/= 1, 2, or 3. 

f: nl ftil c Text is to be changed in the range line nl to line nl. If nl = nl. the range may be 

abbeviated to nl. 

The original contents of the range follows immediately after a c indication. When the contents of two 
files are identical, the contents of the lower-numbered file is suppressed. 

Under the -e option, diffS publishes a script for the editor ed that will incorporate into filel all changes 
between filel and fileS, i.e. the changes that normally would be flagged == and =3. Option -x 
(-3) produces a script to incorporate only changes flagged (===3). The following command will 
apply the resulting script to ‘filel’. 

(cat script; echo 'USpO | ed - filel 

The -E and -X are similar to -e and -x, respectively, but treat overlapping changes (i.e., changes that 
would be flagged with —= in the normal listing) differently. The overlapping lines from both files 
will be inserted by the edit script, bracketed by "«««" and "»»»" lines. 

For example, suppose lines 7-8 are changed in both filel and file2. Applying the edit script generated 
by the command 

"diff3 -E filel file2 file3" 

to filel results in the file: 

lines 1-6 
of filel 

«««< filel 
lines 7-8 
of filel 


lines 7-8 
of file3 

»»»> file3 
rest of filel 

The -E option is used by RCS merge (1) to insure that overlapping changes in the merged files are 
preserved and brought to someone’s attention. 

FILES 

/tmp/d3????? 

/usr/lib/diff3 
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SEE ALSO 

cliff(l) 

BUGS 

Text lines that consist of a single will defeat 
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NAME 

du - summarize disk usage 
SYNOPSIS 

du [ -« ] [ -a ] [ name ... ] 

DESCRIPTION 

Du gives the number of kilobytes contained in all files and, recursively, directories within each specified 
directory or file name. If name is missing, is used. 

The argument -s causes only the grand total to be given. The argument -a causes an entry to be gen¬ 
erated for each file. Absence of either causes an entry to be generated for each directory only. 

A file which has two links to it is only counted once. 

SEE ALSO 

df(l) 

BUGS 

Non-directories given as arguments (not under -sl option) are not listed. 

If there are too many distinct linked files, du counts the excess files multiply. 
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NAME 

echo - echo arguments 

SYNOPSIS 

echo [ -n ] [ arg ] ... 

DESCRIPTION 

Echo writes its arguments separated by blanks and terminated by a newline on the standard output. If 
the flag -n is used, no newline is added to the output. 

Echo is useful for producing diagnostics in shell programs and for writing constant data on pipes. To 
send diagnostics to the standard error file, do ‘echo ... 1>&2’. 
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NAME 

ed - text editor 
SYNOPSIS 

ed [ - ] [ -X ] [ name ] 

DESCRIPTION 

Ed is the standard text editor. 

If a name argument is given, ed simulates an e command (see below) on the named file; that is to say, 
the file is read into eds buffer so that it can be edited. If -x is present, an x command is simulated 
first to handle an encrypted file. The optional - suppresses the printing of explanatory output and 
should be used when the standard input is an editor script 

Ed operates on a copy of any file it is editing; changes made in the copy have no effect on the file until 
a w (write) command is given. The copy of the text being edited resits in a temporary file called the 
buffer. 

Commands to ed have a simple and regular structure: zero or more addresses followed by a single char¬ 
acter command, possibly followed by parameters to the command. These addresses specify one or more 
lines in the buffer. Missing addresses are supplied by default. 

In general, only one command may appear on a line. Certain commands allow the addition of text to 
the buffer. While ed is accepting text, it is said to be in input mode. In this mode, no commands are 
recognized; all input is merely collected. Input mode is left by typing a period alone at the begin¬ 
ning of a line. 

Ed supports a limited form of regular expression notation. A regular expression specifies a set of 
strings of characters. A member of this set of strings is said to be matched by the regular expression. 
In the following specification for regular expressions the word ‘character’ means any character but new- 
line. 

1 . 

2 . 

3. 

4. 

5. 

6 . 

7. 

8 . 


9. 

10 . 
11 . 
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Any character except a special character matches itself. Special characters are the regular 
expression delimiter plus \ [. and sometimes ' ♦ $. 

A . matches any character. 

A \ followed by any character except a digit or () matches that character. 

A nonempty string s bracketed [s] (or fj]) matches any character in (or not in) s. In s, \ has 
no special meaning, and ] may only appear as the first letter. A substring a-b, with a and b in 
ascending ASCII order, stands for Ae inclusive range of ASCII characters. 

A regular expression of form 1-4 followed by ♦ matches a sequence of 0 or more matches of 
the regular expression. 

A regular expression, x, of form 1-8, bracketed Xx\) matches what x matches. 

A \ followed by a digit n matches a copy of the string that the bracketed regular expression 
beginning with the nth X matched. 

A regular expression of form 1-8, x, followed by a regular expression of form 1-7, y matches a 
match for x followed by a match for y, with the x match being as long as possible while still 
permitting a y match. 

A regular expression of form 1-8 preceded by " (or followed by $), is constrained to matches 
that begin at the left (or end at the right) end of a line. 

A regular expression of form 1-9 picks out the longest among the leftmost matches in a line. 

An empty regular expression stands for a copy of the last regular expression encountered. 
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Regular expressions are used in addresses to specify lines and in one command (see s below) to specify 
a portion of a line which is to be replaced. If it is desired to use one of the regular expression meta¬ 
characters as an ordinary character, that character may be preceded by ‘V. This also applies to the 
character bounding the regular expression (often */*) and to ‘V itself. 

To understand addressing in ed it is necessary to know that at any time there is a current line. Gen¬ 
erally speaking, the current line is the last line affected by a command; however, the exact effect on the 
current line is discussed under the description of the command. Addresses are constructed as follows. 

1. The charact^ addresses the current line. 

2. The character *$’ addresses the last line of the buffer. 

3. A decimal number n addresses the n-th line of the buffer. 

4. ‘Oc’ addresses the line mariced with the name x, which must be a lower-case letter. Lines are 

marked with the k command described below. 

5. A regular expression enclosed in slashes */* addresses the line found by searching forward from 
the cunent line and stopping at the first line containing a string that matches the regular 
expression. If necessary the search wraps around to the beginning of the buffer. 

6. A regular expression enclosed in queries *?’ addresses the line found by searching backward 
from the current line and stopping at the first line containing a string that matches the regular 
expression. If necessary the search wr^s around to the end of the buffer. 

7. An address followed by a plus sign *+’ or a minus sign followed by a decimal number 
specifies that address plus (resp. minus) the indicated number of lines. The plus sign may be 
omitted. 

8. If an address begins with *+’ or the addition or subtraction is taken with respect to the 
current line; e.g. ‘-5’ is understood to mean ‘.-5’. 

9. If an address ends with *+’ or then 1 is added (resp. subtracted). As a consequence of this 
rule and rule 8, the address refers to the line before the current line. Moreover, trailing ‘-t-’ 
and characters have cumulative effect, so ‘—’ refers to the current line less 2. 

10. To maintain compatibility with earlier versions of the editor, the character in addresses is 
equivalent to 

Commands may require zero, one, or two addresses. Commands which require no addresses regard the 
presence of an address as an error. Commands which accept one or two addresses assume default 
addresses when insufficient are given. If more addresses are given than such a command requires, the 
last one or two (depending on what is accepted) are used. 

Addresses are separated from each other typically by a comma They may also be separated by a 
semicoltm In this case the current line is set to the previous address before the next address is 
interpreted. This feature can be used to determine the starting line for forward and backward searches 
(7\ *?’). The second address of any two-address sequence must correspond to a line following the line 
corresponding to the first address. The special form *%’ is an abbreviation for the address pair ‘1,$’. 

In the following list of ed commands, the default addresses are shown in parentheses. The parentheses 
are not part of the address, but are used to show that the given addresses are the default. 

As mentioned, it is generally illegal for more than one command to appear on a line. However, most 
commands may be suffixed by ‘p’ or by T’, in which case the current line is either printed or listed 
respectively in the way discussed below. Commands may also be suffixed by ‘n’, meaning the output 
of the command is to be line numbered. These suffixes may be combined in any order. 

(.)a 

<text> 
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The append command reads the given text and appends it after the addressed line. is left on 
the last line input, if th^ any, otl^rwise at ^e addressed line. Address ‘0’ is legal for this 
command; text is placed at the beginning of the buffer. 

(...)c 

<text> 

The change command deletes the addressed lines, then accepts input text which replaces these 
lines. is left at the last line input; if th^ were none, it is left at the line preceding the deleted 
lines. 

The delete command deletes the addressed lines from the buffer. The line originally after the last 
line deleted becrnnes the current line; if the lines deleted were originally at the end, the new last 
line becomes the current line. 

e filename 

The edit command causes the entire cmitents of the buffer to be deleted, and then the named file 
to be read in. *.* is set to the last line of the buffer. The number of characters read is typed, 
‘filename* is remembered fcH* possible use as a default file name in a subsequent r or w command. 
If ‘filename* is missing, the remembered name is used. 

E filename 

This command is the same as e, except that no diagnostic results when no w has been given since 
the last buffer alteration. 

f filename 

The filename command prints the currently remembered file name. If ‘filename* is given, the 
currently remembered file name is changed to ‘filename*. 

(l,$)g/regular expression/command list 

In the global command, the first step is to mark every line which matches the given regular 
expression. Then for every such line, the given command list is executed with ‘.* initially set to 
that line. A single command or the first of multiple commands appears on the same line with the 
global command. All lines of a multi-line list except the last line must be ended with ‘V. A, i. 
and c commands and associated input are permitted; the ‘.* terminating input mode may be omit¬ 
ted if it would be on the last line of the command list The commands g and v are not permitted 
in the command list 

(.)i 

<text> 

This command ins^ the given text before the addressed line. ‘.* is left at the last line input or, 
if there woe none, at the line before the addressed line. This command differs fi'om the a com¬ 
mand only in the placement of the text 

This command joins the addressed lines inU) a single line; intermediate newlines simply disap¬ 
pear. ‘.* is left at the resulting line. 

(Okx 

The mark command marks the addressed line with name x, which must be a lower-case letter. 
The address form ‘'x* then addresses this line. 

(...)! 

The list command prints the addressed lines in an unambiguous way: non-graphic characters are 
printed in two-digit octal, and long lines are folded. The / command may be placed on the same 
line after any non-i/o command. 
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(., .)nw 

The move command repositions the addressed lines after the line addressed by a. The last of the 
moved lines becomes the current line. 

(.,.)P 

The print command prints the addressed lines. is left at the last line printed. The p command 
may be placed on the same line after any non-i/o command. 

(...)P 

This command is a synonym for p. 

q The quit command causes ed to exit. No automatic write of a file is done. 

Q This c(»nmand is the same as q, except that no diagnostic results when no w has been given since 
the last buffer alteration. 

($)r filename 

The read command reads in the given file after the addressed line. If no file name is given, the 
remembered file name, if any, is used (see e and / commands). The file name is remembered if 
there was no remembwed file name already. Address ‘0’ is legal for r and causes the file to be 
read at the beginning of the buffer. If the read is successful, the number of characters read is 
typed. is left at the last line read in from the file. 

( .,.) s/regular expression/replacement/ or, 

( .)s/regular expression/replacemenl/g 

The substitute command searches each addressed line for an occurrence of the specified regular 
expression. On each line in which a match is found, all matched strings are replaced by the 
replacement specified, if the global replacement indicator ‘g’ appears after the command. If the 
global indicator does not appear, only the first occurrence of the matched string is replaced. It is 
an error for the substitution to fail on all addressed lines. Any punctuation character may be used 
instead of V’ to delimit the regular expression and the replacement is left at the last line sub¬ 
stituted. 

An am^rsand *&’ appearing in the replacement is replaced by the string matching the regular 
expression. The special meaning of *&’ in this context may be suppressed by preceding it by ‘V. 
The characters 'Vt’ where n is a digit, are replaced by the text matched by the n-th regular subex¬ 
pression enclosed between *\( and *N)’. When nested, parenthesized subexpressions are present, n 
is detomined by counting occurrences of X’ starting from the left. 

Lines may be split by substituting new-line characters into them. The new-line in the replace¬ 
ment string must be escsqjed by preceding it by ‘\’. 

One or two trailing delimiters may be omitted, implying the ‘p’ suffix. The special form ‘s’ fol¬ 
lowed by no delimiters repeats the most recent substitute command on the addressed lines. The 
‘s’ may be followed by the letters r (use the most recent regular expression for the left hand side, 
instead of the most recent left hand side of a substitute command), p (complement the setting of 
the p suffix from the previous substitution), or g (complement the setting of the g suffix). These 
letters may be combined in any order. 

(.,.)ta 

This command acts just like the m command, except that a copy of the addressed lines is placed 
after address a (which may be 0). is left on the last line of the copy. 

(., .)u 

The undo command restores the buffer to it’s state before the most recent buffer modifying com¬ 
mand. The current line is also restored. Buffer modifying commands are a, c, d, g, i, k, and v. 

For purposes of undo, g and v are considered to be a single buffer modifying command. Undo is 
its own inverse. 

When ed runs out of memory (at about 8000 lines on any 16 bit mini-computer such as the PDP- 
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11) This, full undo is not possible, and u can only undo the effect of the most recent substitute on 
the current line. This restricted undo also applies to editor scripts when ed is invoked with the - 
option. 

(1, $)v/regular expression/command list 

This command is the same as the global command g except that the command list is executed g 
with initially set to evoy line except those matching the regular expression. 

(1, $)w filename 

The write command writes the addressed lines onto the given file. If the file does not exist, it is 
created. The file name is rmiembered if th^ was no remembered file name already. If no file 
name is given, the remembered file name, if any, is used (see e and / commands). is 
unchanged. If the command is successful, the number of characters written is printed. 

(1, $)W filename 

This command is the same as w, except that the addressed lines are appended to the file. 

(1, $)wq filename 

This command is the same as w except that afterwards a q command is done, exiting the editor 
after the file is written. 

X A key string is demanded from the standard input Later r, e and w commands will encrypt and 
decrypt the text with this key by the algorithm of crypt (1). An explicitly empty key turns off 
encryption. (.+l)z or, 

(.+l)zn 

This command scrolls through the buffer starting at the addressed line. 22 (or n, if given) lines 
are printed. The last line printed becomes the current line. The value n is sticky, in that it 
becomes the default for future z commands. 

($) = The line number of the addressed line is typed. is unchanged by this command. 

!<shell command> 

The remainder of the line after the *!’ is sent to sh{l) to be interpreted as a command. is 
unchanged. 

(.+1,.+1) <ne wline> 

An address alone cm a line causes the addressed line to be printed. A blank line alone is 
equivalent to *.+lp’; it is useful for stepping through text. If two addresses are present with no 
intervening semicolon, ed prints the range of lines. If they are separated by a semicolon, the 
second line is printed. 

If an interrupt signal (ASCII DEL) is sent, ed prints ‘?interrupted’ and returns to its command level. 

Some size limitations: 512 characters per line, 256 characters per global command list, 64 characters 
per file name, and, on mini computers, 128K characters in the temporary file. The limit on the number 
of lines depends on the amount of core: each line takes 2 words. 

When reading a file, ed discards ASCII NUL characters and all characters after the last newline. It 
refuses to read files containing non-ASCII characters. 

FILES 

/tmp/e* 

edhup: work is saved here if terminal hangs up 
SEE ALSO 

B. W. Kemighan, A Tutorial Introduction to the ED Text Editor 
B. W. Kemighan, Advanced editing on UNIX 
ex(l), sed(l), crypt(l) 
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DIAGNOSTICS 

‘?name’ for inaccessible file; ‘?self-explanatory message’ for other errors. 

To protect against throwing away valuable work, zl q or e command is considered to be in error, unless 
a w has occurred since the last buffer change. A second qoi e will be obeyed regardless. 


BUGS 

The / command mishandles DEL. 

The undo command causes marks to be lost on affected lines. 

The X command, -x option, and special treatment of hangups only work on UNIX. 
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NAME 

efl - Extended Fortran Language 
SYNOPSIS 

efl [ option ... ] [ filename ... ] 

DESCRIPTION 

Efl compiles a program written in the EFL language into clean Fortran. Efl provides the same control 
flow constructs as does ratfor{\)^ which are essentially identical to those in C: 

statement grouping with braces; 

decision-making with if, if-else, and switch-case; while, for, Fortran do, repeat, and 
repeat...until loops; multi-level break and next In addition, EFL has C-like data structures, and 
more uniform and convenient input/output syntax, generic functions. EFL also provides some 
syntactic sugar to make programs easier to r^ and write: 

free form input: 

multiple statements/line; automatic continuation statement label names (not just numbers), 

comments: 

# this is a comment 

translation of lelationals: 

>, >=, etc., become .GT., .GE., etc. 

return (expression) 

returns expression to caller from function 
define: define name replacement 
include: include filename 

The Efl command option -w suppresses warning messages. The option -C causes comments to be 
copied through to the Fortran output (default); -# prevents comments from being copied through. If a 
command argument contains an embedded equal sign, that argument is treated as if it had appeared in 
an option statement at the beginning of the program. Efl is best used with/77(l). 

SEE ALSO 

f77(l), ratfor(l). 

S. I. Feldman, The Programming Language EFLy Bell Labs Computing Science Technical Report #78. 
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delim $$ 

NAME 

eqn, neqn, checkeq - typeset mathematics 
SYNOPSIS 

eqn [ -dxy ] [ -pn ] [ -sn ] [ -fn ] [ file ]... 
checkeq [ file ] ... 

DESCRIPTION 

Eqn is a troff(l) preprocessor for typesetting mathematics on a Graphic Systems phototypesetter, neqn 
on terminals. Usage is almost always 

eqn file ... I troff 
neqn file ... I nroff 

If no files are specified, these programs read from the standard input. A line beginning with ‘.EQ’ 
marks the start of an equation; the end of an equation is mariced by a line beginning with ‘.EN’. Nei¬ 
ther of these lines is altered, so they may be defined in macro packages to get centering, numbering, 
etc. It is also possible to set two characters as ‘delimitos’; subsequent text between delimiters is also 
treated as eqn input Delimiters may be set to characters x and y with the command-line argument -cLty 
or (more commonly) with ‘delim xy’ betwewi £Q and JEN. The left and right delimiters may be ident¬ 
ical. Delimiters are turned off by ‘delim off. All text that is neither between delimiters nor between 
EQ and .EN is passed through untouched. 

The program checkeq reports missing or unbalanced delimiters and .EQ/JEN pairs. 

Tokens within eqn are separated by spaces, tabs, newlines, braces, double quotes, tildes or circumflexes. 
Braces {} are used for grouping; generally speaking, anywhere a single character like x could appear, a 
complicated construction enclosed in braces may be used instead. Tilde " represents a full space in the 
output, circumflex " half as much. 

Subscripts and superscripts are produced with the keywords sub and sup. Thus x sub i makes $x sub i$, 
a sub i sup 2 produces $a sub i sup 2$, and e sup [x sup 2 + y sup 2] gives $e sup {x sup 2 + y sup 
2}$. 

Fractions are made with over: a over b yields $a over b$. 

sqrt makes square roots: 1 over sqrt [ax sup 2 +&c+c) results in $1 over sqrt {ax sup 2 +bx+c}$ . 

The keywords from and to introduce lower and upper limits on arbitrary things: Slim from {n-> inf) 
sum from 0 to n x sub i$ is made with Urn from {«-> inf ) sum from 0 to n x sub i. 

Left and right brackets, braces, etc., of the right height are made with left and right: left [ x sup 2 + y 
sup 2 over alpha right ] produces Sleft [ x sup 2 + y sup 2 over alpha right ] ”=”1$. The right 
clause is optional. Legal characters after left and right are braces, brackets, bars, c and f for ceiling 
and floor, and "" for nothing at all (useful fw a right-side-only bracket). 

Vertical piles of things are made with pile, IpUe, cpile, and rpile: pile [a above b above c) produces 
Spile {a above b above c)S. There can be an arbitrary number of elements in a pile. Ipile left-justifies, 
pile and cpile center, with different vertical spacing, and rpile right justifies. 

Matrices are made with matrix: matrix { Icol { x sub i above y sub 2 } ccol { 1 above 2 } } produces 
Smatrix ( Icol { x sub i above y sub 2 } ccol { 1 above 2 ) )S. In addition, there is rcol for a right- 
justified column. 

Diacritical marks are made with dot, dotdot, hat, tilde, bar, vec, dyad, and under: x dot =f(t) bar is 
Sx dot = f(t) barS, y dotdot bar " n under is Sy dotdot bar ■'=“ n underS, and x vec ~=~ y dyad is Sx 
vec ■=” y dyadS. 
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Sizes and font can be changed with size n or size ±n, roman, italic, bold, and font n. Size .and fonts 
can be changed globally in a document by gsize n and gfont n, or by the command-line arguments -sn 
and -f«. 

Normally subscripts and superscripts are reduced by 3 point sizes from the previous size; this may be 
changed by the command-line argument -pn. 

Successive display arguments can be lined up. Place mark before the desired lineup point in the first 
equation; place lineup at the place that is to line up vertically in subsequent equations. 

Shorthands may be defined or existing keywords redefined with define; define thing % replacement % 
defines a new token called thing which will be replaced by replacement whenever it appears thereafter. 
The % may be any character that does not occur in replacement. 

Keywords like sum ( sum ) int (int) inf (inf ) and shorthands like >= (>=) -> (->), and !=(!=) are 
recognized. Greek letters are spelled out in the desired case, as in alpha or GAMMA. Mathematical 
words like sin, cos, log are made Roman automatically. TroffO) four-character escapes like \(bs (#) 
can be used anywhere. Strings enclosed in double quotes "..." are passed through untouched; this per¬ 
mits keywords to be entoed as text, and can be used to communicate with trojf when aU else fails. 

SEE ALSO 

troff(l), tbl(l), ms(7), eqnchar(7) 

B. W. Kemighan and L. L. Cherry, Typesetting Mathematics — User’s Guide 
J. F. Ossanna, NROFF/TROFF User’s Manual 

BUGS 

To embolden digits, parens, etc., it is necessary to quote them, as in ‘bold "12.3"’. 
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NAME 

error - analyze and disperse compiler error messages 
SYNOPSIS 

error [ -n ] [ -s ] [ -q ] [ -v ] [ -t suffixlist ] [ -I ignorefile ] [ name ] 

DESCRIPTION 

Error analyzes and optionally disperses the diagnostic error messages produced by a number of com¬ 
pilers and language processors to the source file and line where the errors occurred. It can replace the 
painful, traditional methods of scribbling abbreviations of errors on paper, and permits error messages 
and source code to be viewed simultaneously without machinations of multiple windows in a screen 
editor. 

Error looks at the error messages, either from the specified file name or firom the standard input, and 
attempts to determine which language processor produced each error message, determines the source 
file and line number to which the error message refers, determines if the error message is to be ignored 
or not, and inserts the (possibly slightly modified) error message into the source file as a comment on 
the line preceding to which the line the error message refers. Error messages which can’t be categor¬ 
ized by language processor or content are not inserted into any file, but are sent to the standard output. 
Error touches source files only after all input has been read. By specifying the -q query option, the 
user is asked to confirm any potentially dangerous (such as touching a file) or verbose action. Other¬ 
wise error proceeds on its merry business. If the -t touch option and associated suffix list is given, 
error will restrict itself to touch only those files with suffices in the suffix list. Error also can be asked 
(by specifying -v) to invoke vi(l) on the files in which error messages were inserted; this obviates the 
need to remember the names of the files with errors. 

Error is intended to be run with its standard input connected via a pipe to the error message source. 
Some language processors put error messages on their standard error file; others put their messages on 
the standard output Hence, both error sources should be piped together into error. For example, when 
using the csh syntax, 

make -s lint I & error -q -v 

will analyze all the error messages produced by whatever programs mdx runs when making lint 

Error knows about the error messages produced by: make, cc, cpp, ccom, as, Id, lint, pi, pc, f77, and 
DEC Western Research Modula-2. Error knows a standard format for error messages produced by the 
language processors, so is sensitive to changes in these formats. For all languages except Pascal, error 
messages are restricted to be on one line. Some error messages refer to more than one line in more 
than one files; error will duplicate the error message and insert it at all of the places referenced. 

Error will do one of six things with error messages. 
synchronize 

Some language processors produce short errors describing which file it is processing. Error 
uses these to determine the file name for languages that don’t include the file name in each 
error message. These synchronization messages are consumed entirely by error. 

discard Error messages from lint that refer to one of the two lint libraries, lusriliblllib-lc and 
/usr/lib/llib-port are discarded, to prevent accidently touching these libraries. Again, these 
error messages are consumed entirely by error. 

nullify Error messages from lint can be nullified if they refer to a specific function, which is 
known to generate diagnostics which are not interesting. Nullified error messages are not 
inserted into the source file, but are written to the standard ouq)uL The names of functions 
to ignore are taken from either the file named .errorrc in the users’s home directory, or 
from the file named by the -I option. If the file does not exist, no error messages are 
nullified. If the file does exist, there must be one function name per line. 

not file specific 
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Error messages that can’t be intuited are grouped together, and written to the standard out¬ 
put before any files are touched. They will not be inserted into any source file. 

file specific Error message that refer to a specific file, but to no specific line, are written to the standard 
output when that file is touched. 

true errors Error messages that can be intuited are candidates for insertion into the file to which they 
refCT. 

Only true error messages are candidates for inserting into the file they refer to. Other error messages 
are consumed entirely by error or are written to the standard output. Error inserts the error messages 
into the source file on the line preceding the line the language processor found in error. Each error 
message is turned into a one line comment fw the language, and is internally flagged with the string 
“###” at the beginning of the errw, and “%%%” at the end of the error. This makes pattern search¬ 
ing for errors easier with an editor, and allows the messages to be easily removed. In addition, each 
error message contains the source line number for the line the message refers to. A reasonably format¬ 
ted source program can be lectMnpiled with the error messages still in it, without having the error mes¬ 
sages themselves cause future orors. For poorly formatted source programs in free format languages, 
such as C or Pascal, it is possible to insert a comment into another comment, which can wreak havoc 
with a future compilation. To avoid this, programs with comments and source on the same line should 
be formatted so that language statements appear before comments. 

Options available with error are: 

-n Do not touch any files; all mor messages are sent to the standard output. 

-q The user is queried whether s/he wants to touch the file. A “y” or “n” to the question is neces¬ 

sary to continue. Absence of the -q option implies that all referenced files (except those referring 
to discarded error messages) are to be touched. 

-v After all files have been touched, overlay the visual editor vr with it set up to edit all files 
touched, and positioned in the first touched file at the first error. If vi can’t be found, try ex or ed 
firom standard places. 

-t Take the following argument as a suffix list. Files whose suffixes do not appear in the suffix list 
are not touched. The suffix list is dot separated, and wildcards work. Thus the suffix list 

".c.y.foo*.h" 

allows error to touch files ending with “.c”, “.y”, “.foo*” and “.y”. 

-s Print out statistics regarding the error categorization. Not too useful. 

Error catches interrupt and terminate signals, and if in the insertion phase, will orderly terminate what 
it is doing. 

AUTHOR 

Robert Henry 

FILES 

“/.errorrc function names to ignore for lint error messages 

/dev/tty user’s teletype 

BUGS 

Opens the teletype directly to do user querying. 

Source files with links make a new copy of the file with only one link to it. 

Changing a language processor’s format of error messages may cause error to not understand the error 
message. 

Error, since it is purely mechanical, will not filter out subsequent errors caused by ‘floodgating’ ini¬ 
tiated by one syntactically trivial error. Humans are still much better at discarding these related errors. 
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Pascal error messages belong after the lines affected (error puts them before). The alignment of the ‘I’ 
marking the point of error is also disturbed by error. 

Error was designed for work on CRT’s at reasonably high speed. It is less pleasant on slow speed ter¬ 
minals, and has never been used on hardcopy terminals. 
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NAME 

eunlogin - log into the EUNICE accounting 

SYNOPSIS 

eunlogin 

DESCRIPTION 

Eunlogin controls the accounting for the number of logins to be allowed access to the UNIX utilities. 
Eunlogin must always be used before accessing the EUNICE environment, using UNIX utilities as 
foreign commands from the DCL, or running UNIX utilities from a DCL command file. Any program 
which is compiled with the EUNICE compilers will contain UNIX code, thus limiting access to that 
program. 

Eunlogin adds the user to access accounting by making an entry in a special global section file which 
keeps track of the number of users in EUNICE. It is AUTOMATICALLY run from 
TWG$ADMIN:CSHELL.COM and other EUNICE command files that need permission to use the UNIX 
libraries. The only time that users should need to run eunlogin by hand is when they use EUNICE 
commands from DCL. 


Eunlogout, the companion program to this utility, is used to log the user out of access accounting. 

Precautions have been taken to compensate for a user’s forgetting to logout of access accounting pre¬ 
cluding a new user from using one of the UNIX utilities; eunlogin will clean up the global section. 
Eunlogin will also clean up the global section for processes that have been killed. If the full number of 
allowable users is already entered in the global section and a new user wishes to be added, eunlogin 
will check the global section for users who are entered, but who don’t have any active processes. The 
inactive account will be replaced with the new user. 


If a binary UNIX license was purchased through The Wollongong Group, the maximum number of 
users (2, 8, 16, 32, 64 or unlimited) allowed is specified on the license. If a company has a source 
license from AT&T, it is possible to buy a binary license associated with the source license. In this 
case, the number of users is unlimited, since the source license is unlimited. Remember: SITES WITH 
UNRESTRICTED LICENSES STILL NEED TO RUN THIS UTILITY. 

EUNICE NOTES 

This is a EUNICE specific command which can only be run from DCL. 


FILES 

/usr/adm/wtmp 
/usr/spool/mail/* 
/etc/motd 
/etc/passwd 
" */.hushlogin 


accounting 

mail 

message-of-the-day 
password file 
makes login quieter 


SEE ALSO 

eunlogout(lW), prtusers(8W), mail(l), passwd(5) 
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NAME 


eunlogout - log out of EUNICE process accounting 


SYNOPSIS 

eunlogout 

DESCRIPTION 

Eunlogout controls the accounting for the number of logins which are allowed access to the UNIX utili¬ 
ties. Since all sites now have to run eunlogin(lW), this program must be run when terminating a EUN¬ 
ICE session. 


Eunlogout logs the user out of access accounting. The entry made with eunlogout’s companion pro¬ 
gram [eunlogin(lW)] in the global section file, is removed by using the eunlogout command so that 
resources may be released to future users of EUNICE. 

As with eunlogin, this program is automatically called from TWG$ADMIN:CSHELL.COM. Normally 
the only time users would invoke it separately is when they need to relinquish EUNICE resources to 
other users who need them. 


NOTE: SITES WITH UNRESTRICTED LICENSES STILL NEED TO RUN THIS UTILITY. 

EUNICE NOTES 

This is a EUNICE specific command which can only be run from DCL. For more details, please refer 
to eunlogin(2W). 

SEE ALSO 

eunlogin(lW), prtusers(8W) 



O 
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NAME 

ex, edit - text editor 
SYNOPSIS 

ex [ - ] [ -V ] [ -t tag ] [ -r ] [ +command ] [ -1 ] name ... 
edit [ ex options ] 

DESCRIPTION 

Ex is the root of a family of editors: edit, ex and vi. Ex is a superset of ed, with the most notable 
extension being a display editing facility. Display based editing is the focus of vi. 

If you have not used ed, or are a casual usct, you will find that the editor edit is convenient for you. It 
avoids some of the complexities of ex used mostly by systems programmers and persons very familiar 
with ed. 

If you have a CRT terminal, you may wish to use a display based editor; in this case see vz(l), which is 
a command which focuses on the display editing portion of ex. 

DOCUMENTATION 

The document Edit: A tutorial (USD: 14) provides a comprehensive introduction to edit assuming no 
previous knowledge of computers or the unk system. 

The Ex Reference Manual - Version 3.7 (USD: 16) is a comprehensive and complete manual for the 
command mode features of ex, but you cannot leam to use the editor by reading it For an introduction 
to more advanced forms of editing using the command mode of ex see the editing documents written by 
Brian Kemighan for the editor ed; the material in the introductory and advanced documents works also 
with ex. 


An Introduction to Display Editing with Vi (USD: 15) introduces the display editor vi and provides refer¬ 
ence material oh vi. In addition, the Vi Quick Reference card summarizes the commands of vi in a use¬ 
ful, functional way, and is useful with the Introduction. 


FILES 

/usr/lib/ex? .?strings 
/usr/lib/ex? .?recover 
/usr/lib/ex?.?preserve 
/etc/termcap 
"/.exTC 

/tmp/Exn/innn 

/tmp/Rxnnwi« 

/usr/preserve 


error messages 

recover command 

preserve command 

describes capabilities of terminals 

editor startup file 

editor temporary 

named buffer temporary 

preservation directory 


SEE ALSO 

awk(l), ed(l), grep(l), sed(l), grep(l), vi(l), termcap(5), environ(7) 


AUTHOR 

Originally written by William Joy 

Mark Heaton has maintained the editor since version 2.7, adding macros, support for many unusual ter¬ 
minals, and other features such as word abbreviation mode. 


BUGS 

The umio command causes all marks to be lost em lines changed and then restored if the marked lines 
were changed. 

Undo never clears the buffer modified condition. 

The z command prints a number of logical rather than physical lines. More than a screen full of output 
may result if long lines are present 


/ 
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File input/output errors don’t print a name if the command line option is used. 

There is no easy way to do a single scan ignoring case. 

The editor does not warn if text is placed in named buffers and not used before exiting the editor. 
Null charact^ are discarded in input files, and cannot appear in resultant files. 
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NAME 

expand, unexpand - expand tabs to spaces, and vice versa 
SYNOPSIS 

expand [ -tabstop ] [ -tabl,tab2,...,tabn ] [ file ... ] 
unexpand [ -a ] [ file ... ] 

DESCRIPTION 

Expand processes the named files or the standard input writing the standard output with tabs changed 
into blanks. Backspace characters are presaved into the output and decrement the column count for tab 
calculations. Expand is useful for pre-processing character files (before sorting, looking at specific 
columns, etc.) that contain tabs. 

If a single tabstop argument is given, then tabs are set tabstop spaces apart instead of the default 8. If 
multiple tabstops are given then the tabs are set at those specific columns. 

Unexpand puts tabs back into the data from the standard input or the named files and writes the result 
on the standard output By default only leading blanks and tabs are reconverted to maximal strings of 
tabs. If the option is given, then tabs are inserted whenever they would compress the resultant file 
by replacing two or more characters. 


April 19, 1989 


The Wollongong Group 


1 



EXPR(l) 


UNIX Programmer’s Manual 


EXPR(l) 


NAME 

expr - evaluate arguments as an expression 

SYNOPSIS 

expr arg ... 

DESCRIPTION 

The arguments are taken as an expression. After evaluation, the result is written on the standard output. 
Each token of the expression is a separate argument 

The operators and keywords are listed below. The list is in order of increasing precedence, with equal 
precedence operators grouped. 

expr I expr 

yields the first expr if it is neither nuU nor ‘O’, otherwise yields the second expr. 
expr & expr 

yields the first expr if neither expr is null or ‘O’, otherwise yields ‘O’. 
expr relop expr 

where relop is one of <<- - != >= >, yields ‘1’ if the indicated comparison is true, ‘0’ if 
false. The comparison is numeric if both expr are integers, otherwise lexicographic. 

expr + expr 
expr - expr 

addition or subtraction of the arguments. 

expr * expr 
expr / expr 
expr % expr 

multiplication, division, or remainder of the arguments. 
expr : expr 

The matching operator compares the string first argument with the regular expression second 
argument; regular expression syntax is the same as that of ed{\). The pattern symbols 

can be used to select a portion of the firet argument. Otherwise, the matching operator yields 
the number of characters matched (‘0’ on failure). 

( expr ) parentheses for grouping. 

Examples: 

To add 1 to the Shell variable a: 
a='expr $a + 1' 

To find the filename part (least significant part) of the pathname stored in variable a, which may or may 
not contain ‘/’: 

expr $a : '.*A(.*\)' 'V $a 

Note the quoted Shell metacharacters. 

SEE ALSO 

sh(l), test(l) 

DIAGNOSTICS 

Expr returns the following exit codes: 

0 if the expression is neither null nor ‘O’, 

1 if the expression is null or ‘O’, 

2 for invalid expressions. 
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NAME 

f77 - Fortran 77 compiler 
SYNOPSIS 

f77 [ option ] ... file ... 

DESCRIPTION 

F77 is the UNIX Fortran 77 compiler. It accepts several types of arguments: 

Arguments whose names end with ‘.F are talsn to be Fortran 77 source programs; they are compiled, 
and each object program is left on the file in the current directory whose name is that of the source 
with ‘.o’ substituted for ’.f. 

Arguments whose names end with ‘JF’ are also taken to be Fortran 77 source programs; these are first 
processed by the C preprocessor before being compiled by/77. 

Arguments whose names end with ‘.r’ or ‘.e’ are taken to be Ratfor or EFL source programs respec¬ 
tively; these are first transformed by the ap}ropriate preprocessor, then compiled by f77. 

Arguments whose names end with ‘.c’ or ‘.s’ are taken to be C or assembly source programs and are 
compiled or assembled, producing a ‘.o’ file. 

The following options have the same meaning as in cc(l). See W(l) for load-time options. 

-c Suppress loading and produce ‘.o’ files for each source file. 

-g Produce additional symbol table information for dbx{\) and pass the -Ig flag to ld{\) so that on 
abnormal terminations, the memory image is written to file core. Incompatible with -O. 

-o output 

Name the final output file output instead of ‘a.out’. 

-p Prepare object files for profiling, see prof{\). 

-pg Causes the compiler to produce counting code in the manner of -p, but invokes a run-time 
recording mechanism that keeps more extensive statistics and produces a gmon.out file at nor¬ 
mal termination. An execution profile can then be generated by use of gprof{\). 

-w Suppress all warning messages. If the option is ‘-w66’, only Fortran 66 compatibility warn¬ 
ings are suppressed. 

-Dname^def 

-Dname 

Define the name to the C preprocessor, as if by ‘#define’. If no definition is given, the name is 
defined as "1". (‘J’ suffix files only). 

-Idir ‘#include’ files whose names do not begin with ‘/’ are always sought first in the directory of 
the file argument, then in directories named in -I options, then in directories on a standard list. 
(‘.F’ suffix files only). 

-O Invoke an object-code optimizer. Incompatible with -g. 

-S Compile the named programs, and leave the assembler-language output on corresponding files 
suffixed ‘.s’. (No ‘.o’ is created.). 

The following options are peculiar to f77. 

-d Used for debugging the compiler. 

-i2 On machines which support short integers, make the default integer constants and variables 
short. (-i4 is the standard value of this option). All logical quantities will be short. 

-q Suppress printing of file names and program unit names during compilation. 

-m Apply the M4 preprocessor to each ‘.r’ file before transforming it with the Ratfor or EFL 
preprocessor. 
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-onetrip 

-1 Compile DO loops that are performed at least once if reached. (Fortran 77 DO loops are not 
performed at all if the upper limit is smaller than the lower limit.) 

-r8 Treat all floating point variables, constants, functions and intrinsics as double precision and all 
complex quantities as double complex. 

-u Make the default type of a variable ‘undefined* rather than using the default Fortran rules. 

-V Print the version number of the compiler, and the name of each pass as it executes. 

-C Compile code to check that subscripts are within declared array bounds. For multi-dimensional 
arrays, only the equivalent linear subscript is checked. 

-F Apply the C preprocessor to ‘.F’ files, and the EFL, or Ratfor preprocessors to ‘.e’ and ‘.r’ 
files, put the result in the file with the suffix changed to ‘.f, but do not compile. 

-Elx Use the string x as an EFL option in processing ‘.e’ files. 

-Rx Use the string x as a Ratfor option in processing ‘.r’ files. 

-N[qxscii]«nn 

Make static tables in the compiler bigger. The compiler will complain if it overflows its tables 
and suggest you apply one or more of these flags. TTiese flags have the following meanings: 

q Maximum number of equivalenced variables. Default is 150. 

X Maximum number of external names (common block names, subroutine and function 
names). Default is 200. 

s Maximum number of statement numbers. Default is 401. 

c Maximum depth of nesting for control statements (e.g. DO loops). Default is 20. 

n Maximum number of identifiers. Default is 1009. 

-U Do not convert upper case letters to Iowct case. The default is to convert Fortran programs to 
lower case except within character string constants. 

Other arguments are taken to be either loader option arguments, or F77-compatible object programs, 
typically produced by an earlier run, or perhaps libraries of F77-compatible routines. These programs, 
together with the results of any compilations specified, are loaded (in the order given) to produce an 
executable program with name ‘a.out’. 

Programs compiled with /77 produce memory dumps in file core upon abnormal termination if the -g 
flag was specified during loading. If the environment variable f77_dumpJlag is set to a value begin¬ 
ning with y or n, dumps for abnormal terminations are respectively forced or suppressed. 

EUNICE NOTES 

The f77 compiler has been modified to create either VMS or UNIX objects. It will read the value of 
the csh variable, ASJMAGE, to determine if the UNIX or VMS assembler should be used. The value 
of LD_IMAGE will determine whether the UNIX or VMS loader should be used as the loader. Add 
the following lines to a .cshrc or .login in your home directory. 

# Have cc(l) or f77(l) use UNIX assembler and loader, 
alias unixobj ’unsetenv ASJMAGE; unsetenv LDJMAGE’ 

# 

# Have cc(l) or f77(l) use VMS assembler and loader. 

alias vmsobj ’setenv AS_IMAGE /usr/eun/vmsas; setenv LDJMAGE /usr/eun/vmsld’ 

Also add either of the following lines, depending on your choice of object type. 

unixobj 
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vmsobj 


The -g flag for additional symbol table information can only be used with UNIX objects. 

FILES 

file.[fFresc] 
file.o 
a.out 

/usr/lib/f77passl 
/Ub/fl 
/Ub/c2 
/lib/cpp 

/usr/lib/libF77.a 
/usr/lib/libI77.a 
/usr/lib/UbU77.a 
/usr/lib/libm.a 
/lib/libc.a 
/usr/lib/libF77_j).a 
/usr/lib/libI77jp.a 
/usr/lib/libU77_p.a 
/usr/lib/libm_p.a 
/usr/lib/libc_p.a 
mon.out 
gmon.out 

SEE ALSO 

S. I. Feldman, P. J. Weinberger, J. Beikman, A Portable Fortran 77 Compiler 

D. L. Wasley, J. Berkman, Introduction to the f77 HO Library 

fpr(l), fsplit(l), ld(l), ar(l), ranlib(l), dbx(l), intro(3f) 

efl(l), ratfor(l), struct(l), prof(l), gprof(l), cc(l), as(l), vmsas(l), vmsld(l) 

DIAGNOSTICS 

The diagnostics produced by /77 itself are intended to be self-explanatory. Occasional messages may 
be produced by the loader. 

BUGS 

Files longer than about 50,000 lines must be split up to be compiled. 


input file 
object file 
loaded output 
compiler 
pass 2 

optional optimizer 
C preprocessor 
intrinsic function library 
Fortran I/O library 
UNIX interface library 
math library 
C library, see section 3 
profiling intrinsic function library 
profiling Fortran I/O library 
profiling UNIX interface library 
profiling math library 
profiling C library, see section 3 
file produced for analysis by prof(I). 
file produced for analysis by gprof(l). 
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O NAME 


false, true - provide truth values 


SYNOPSIS 

true 

false 


DESCRIPTION 

True and false are usually used in a Bourne shell script They test for the appropriate status "true" or 
"false" before running (or failing to run) a list of commands. 

EXAMPLE 


while false 
do 

command list 
done 


SEE ALSO 

csh(l), sh(l), true(l) 

DIAGNOSTICS 

False has exit status nonzero. 
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NAME 

file - determine file type 

SYNOPSIS 

file file ... 

DESCRIPTION 

File performs a series of tests on each argument in an attempt to classify it. If an argument appears to 
be ascii, examines the first 512 bytes and tries to guess its language. 

EUNICE NOTES 

File(l) returns "data" for stripped executable objects, "commands text" for text files with execute per¬ 
mission and "ascii text" for text files without execute permission. Below are other possible responses 
from file(l): 

commands text (see above) 
data (see above) 
ascii text (see above) 
ascii text with garbage 
English text 

jfr or pdp-11 Unix 411 executable 
executable not stripped 

executable not stripped old format symbol table 
very old archive 
old archive 
archive 

archive random library 
cpio data 
c program text 
fortran program text 
assembler program text 
roff, nroff, or eqn input text 
troff (CAT) output 
troff intermediate output text 
C-shell script 
C-shell commands 

demand paged pure executable not stripped 
symbolic link to "library" 

BUGS 

It often makes mistakes. In particular it often suggests that command files are C programs. 

Does not recognize Pascal or LISP. 
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NAME 

filetype - provides information about the file type 

SYNOPSIS 

filetype name 

DESCRIPTION 

Filetype displays the type of file (UNIX or VMS), for file name. 
EUNICE NOTES 

Filetype is a EUNICE BSD specific command. It is stored in lusriem. 

SEE ALSO 

file(l) 
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NAME 

find - find files 
SYNOPSIS 

find pathname-list expression 
find pattern 

DESCRIPTION 

In the first form above, find recursively descends the directory hierarchy for each pathname in the 
pathncune-list (i.e., one or more pathnames) seeking files that match a boolean expression written in the 
primaries given below. In the descriptions, the argument n is used as a decimal integer where +n 
means more than n, -n means less than n and n means exactly n. 

The second form rapidly searches a database for all pathnames which match pattern. Usually the data¬ 
base is recomputed weekly and contains the pathnames of all files which are publicly accessible. If 
escaped, normal shell “globbing” characters *?’, ‘[’, and ’]’) may be used in pattern, but the 
matching differs in that no characters {e.g. T) have to be matched explicitly. As a special case, a sim¬ 
ple pattern containing no globbing characters is matched as though it were * pattern*’, if any globbing 
character appears there are no implicit globbing characters. 

-name filename 

True if the filename argument matches the current file name. Normal shell argument syntax 
may be used if escaped (watch out for *[’, *?’ and 

-perm onum 

True if the file permission flags exactly match the octal number onum (see chmod(l)). If 
onum is prefixed by a minus sign, more flag bits (017777, see stat(2)) become significant 
and the flags are compared: (ftags&onum)--onum. 

-type c True if the type of the file is c, where c is b, c, d, f, 1 or s for block special file, character 
special file, directory, plain file, symbolic link, or socket. 

-links n True if the file has n links. 

-user uname 

True if the file belongs to the user uname Gogin name or numeric user ID). 

-nouser True if the file belongs to a user not in the /etc/passwd database. 

-group gname 

True if the file belongs to group gname (group name or numeric group ID). 

-nogroup True if the file belongs to a group not in the /etc/group database. 

-size n True if the file is n blocks long (512 bytes per block). 

-inum n True if the file has inode number n. 

-atime n True if the file has been accessed in n days. 

-mtime n True if the file has been modified in n days. 

-exec command 

True if the executed command returns a zero value as exit status. The end of the command 
must be punctuated by an escaped semicolon. A command argument ‘O’ is replaced by 
the current pathname. 

-ok command 

Like -exec except that the generated command is written on the standard output, then the 
standard input is read and the command executed only upon response y. 

-print Always true; causes the current pathname to be printed. 

-Is Always true; causes current pathname to be printed together with its associated statistics. 
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These include (respectively) inode number, size in kilobytes (1024 bytes), protection mode, 
number of hard lii^, user, group, size in bytes, and modification time. If the file is a spe¬ 
cial file the size field will instead contain the major and minor device numbers. If the file 
is a symbolic link the pathname of the linked-to file is printed preceded by The for¬ 

mat is identical to that of “Is -gilds’* (note however that formatting is done internally, 
without executing the Is program). 

-newer file 

True if the current file has been modified more recently than the argument file. 

-cpio file Write the current file on the argument file in cpio format 

-xdev Always true; causes find not to traverse down into a file system different from the one on 
which current argument pathname resides. 

The primaries may be combined using the following operators (in order of decreasing precedence): 

1) A parenthesized group of primaries and operators (parentheses are special to the Shell and must be 
escaped). 

2) The negation of a primary (*!’ is the unary not operator). 

3) ConcatenaticHi of primaries (the and operation is implied by the juxtaposition of two primaries). 

4) Alternation of primaries (‘-o’ is the or operator). 

EUNICE NOTES 

The message, "find: bad status < filename >", will be reported if the file is not readable by the user. 
This is a restriction of the VMS file system. It will allow a user to read the names of the contents of a 
directory as long as the directory is executable by the user. Non-readable directory entries cannot be 
stated. Ignore the message. 

/usr/lib/find/updatedb should be run periodically on changed files in your file tree. This executable file 
creates the /usrllib/find/find.codes file used by the second form of find(l). 

EXAMPLES 

To find all accessible files whose pathname contains ‘find’: 
find find 

To typeset all variants of manual pages for ‘Is’: 
vtroff -man ‘find ’*man*/ls.?’‘ 

To remove all files named ‘a.out’ or ‘*.o’ that have not been accessed for a week: 
find / X -name a.out -o -name ’*.o’ \) -atime +7 -exec rm {) \ 

FILES 

/etc/passwd 

/etc/group 

/usr/lib/find/find.codes coded pathnames database 
/usr/lib/find/updatedb 

SEE ALSO 

sh(l), test(l), fs(5) 

Relevant paper in February, 1983 issue of .login:. 

BUGS 

The first form’s syntax is painful, and the second form’s exact semantics is confusing and can vary 
from site to site. 
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More than one ‘-newer’ option does not work properly. 
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NAME 

finger - user information lookup program 
SYNOPSIS 

finger [ options ] name ... 

DESCRIPTION 

By default finger lists the login name, full name, terminal name and write status (as a *♦’ before the ter¬ 
minal name if write permission is denied), idle time, login time, and office location and phone number 
(if they are known) for each current UNIX user. (Idle time is minutes if it is a single integer, hours and 
minutes if a is present, or days and hours if a’d’ is present) 

A longer format also exists and is used by finger whenever a list of people’s names is given. (Account 
names as well as first and last names of users are accepted.) This format is multi-line, and includes all 
the information described above as well as the user’s home directory and login shell, any plan which 
the person has placed in the file .plan in their home directory, and the project on which they are work¬ 
ing from the file .project also in the home directory. 

Finger may be used to lookup users on a remote machine. The format is to specify the user as 
“user@host.” If the user name is left off, the standard format listing is provided on the remote 
machine. 


Finger options include: 

-m Match arguments only on user name. 
-1 Force long outi)ut format 

-p Suppress printing of the .plan files 
-s Force short output format 


FILES 

/etc/utmp 

/etc/passwd 

/usr/adm/lastlog 

"/.plan 

"/.project 

SEE ALSO 

chfn(l), w(l), who(l) 

AUTHOR 

Earl T. Cohen 


who file 

for users names, offices,... 

last login times 

plans 

projects 


BUGS 

Only the first line of the .project file is printed. 

The encoding of the geos field is UCB dependent - it knows that an office ‘197MC’ is ‘197M Cory 
Hall’, and that ‘529BE’ is ‘529B Evans Hall’. It also knows that a four digit office phone number 
should have a “x2-” prepended. 

There is no way to pass arguments to the remote machine as finger uses an internet standard port. 

A user information data base is in the works and will radically alter the way the information that finger 
uses is stored. Finger will require extensive modification when this is implemented. 
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NAME 

fmt - simple text formatter 

SYNOPSIS 

fmt [ name ... ] 

DESCRIPTION 

Fmt is a simple text formatter which reads the concatenation of input files (or standard input if none are 
given) and produces on standard output a version of its input with lines as close to 72 characters long 
as possible. The spacing at the beginning of the input lines is preserved in the output, as are blank 
lines and interword spacing. 

Fmt is meant to format mail messages prior to sending, but may also be useful for other simple tasks. 
For instance, within visual mode of the ex editor (e.g. vi) the command 
!}fmt 

will reformat a paragraph, evening the lines. 

SEE ALSO 

nroff(l), mail(l) 

AUTHOR 

Kurt Shoens 

BUGS 

The program was designed to be simple and fast - for more complex operations, the standard text pro¬ 
cessors are likely to be more appropriate. 
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NAME 

fold - fold long lines for finite width output device 
SYNOPSIS 

fold [ -width ] [ file ... ] 

DESCRIPTION 

Fold is a filter which will fold the contents of the specified files, or the standard input if no files are 
specified, breaking the lines to have maximum width width. The default for width is 80. Width should 
be a multiple of 8 if tabs are present, or the tabs should be expanded using expand{\) before coming to 
fold. 

SEE ALSO 

expand(l) 

BUGS 

If underlining is present it may be messed up by folding. 
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NAME 

fp - Functional Programming language compiler/interpreter 
SYNOPSIS 

fp 

DESCRIPTION 

Fp is an interpreter/compiler that implements the applicative language proposed by John Backus. It is 
written in FRANZ USP. 

In a functional programming language intent is expressed in a mathematical style devoid of assign¬ 
ment statements and variables. Functions compute by value only; there are no side-effects since the 
result of a computation depends solely on the inputs. 

Fp "programs" consist oi functional expressions - primitive and user-defined fp functions combined by 
functional forms. These forms take functional arguments and return functional results. For example, the 
composition operator takes two functional arguments and returns a function which represents their 
composition. 

There exists a single operation in fp - application. This operation causes the system to evaluate the 
indicated function using the single argument as input (all functions are monadic). 

EUNICE NOTES 

Control Z exits back to the shell. Control Y terminates any computation in progress. 

GETTING STARTED 

Fp invokes the system. Fp compiles functions into lispiX) source code; lispO) interprets this code (the 
user may compile this code using the liszt (1) ctanpiler to gain a factor of 10 in performance). Control 
D exits back to the shell. Break terminates any computation in progress and resets any open file units. 
help provides a short summary of all user commands. 

FILES 

/usr/ucb/lisp the FRANZ LISP interpreter 

/usr/ucb/liszt the liszt compiler 

/usr/doc/fp the User’s Guide 

SEE ALSO 

lisp(l), liszt(l). 

The Berkeley FP user’s manual, available on-line. The language is described in the August 1978 
issue of CACM (Turing award lecture by John Backus). 

BUGS 

If a non-terminating function is applied as the result of loading a file, then control is returned to the 
user immediately, everything after that position in the file is ignored. 

FP incorrectly marks the location of a syntax error on large, multi-line function definitions or applica¬ 
tions. 

AUTHOR 

Scott B. Baden 
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NAME 

fjpr - print Fortran file 

SYNOPSIS 

fpr 

DESCRIPTION 

Fpr is a filter that transforms files formatted according to Fortran’s carriage control conventions into 
files formatted according to UNIX line printer conventions. 

Fpr copies its input onto its output, replacing the carriage control characters with characters that will 
produce the intended effects when printed using lpr{\). The first character of each line determines the 
vertical spacing as follows: 


Character 

Vertical Space Before Printing 

Blank 

0 

1 

+ 

One line 

Two lines 

To first line of next page 

No advance 


A blank line is treated as if its first character is a blank. A blank that appears as a carriage control char¬ 
acter is deleted. A zero is changed to a newline. A one is changed to a form feed. The effects of a "+" 
are simulated using backspaces. 

EXAMPLES 

a.out I fpr I Ipr 

fpr < f77 .output I Ipr 

BUGS 

Results are undefined for input lines longer than 170 characters. 
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NAME 

from - who is my mail from? 

SYNOPSIS 

from [ -s send^ ] [ user ] 

DESCRIPTION 

From prints out the mail header lines in your mailbox file to show you who your mail is fr’om. If user 
is specified, then user*s mailbox is examined instead of your own. If the -s option is given, then only 
headers for mail sent by sender are printed. 

FILES 

/usr/spool/mail/* 

SEE ALSO 

biff(l), mail(l) 
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NAME 

fsplit - split a multi-routine Fortran file into individual files 
SYNOPSIS 

fsplit [ -e efile] ... [ file ] 

DESCRIPTION 

Fsplit takes as input either a file or standard input containing Fwiran source code. It attempts to split 
the input into separate routine files of the form name./, where ncune is the name of the program unit 
(e.g. function, subroutine, block data or program). The name for unnamed block data subprograms has 
the form blkdtoNNNf where NNN is three digits and a file of this name does not already exist. For 
unnamed main programs the name has the form mainNNNf. If there is an error in classifying a program 
unit, or if name/ already exists, the program unit will be put in a file of the form zzzNNN.f where 
zzzNNNfdo&s not already exist 

Normally each subprogram unit is split into a separate file. When the -e option is used, only the 
specified subprogram units are split into separate files. E.g.: 

fsplit -e readit -e doit prog.f 
will split readit and doit into separate files. 

DIAGNOSTICS 

If names specified via the -e option are not found, a diagnostic is written to standard error. 

AUTHOR 

Asa Romberger and Jerry Berkman 

BUGS 

Fsplit assumes the subprogram name is on the first noncomment line of the subprogram unit. Nonstan¬ 
dard source formats may confuse fsplit. 

It is hard to use -e for unnamed main programs and block data subprograms since you must predict the 
created file name. 
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NOTE 


WOLLONGONG’S WIN/TCP PRODUCT 


NAME 

ftp - ARPANET file transfer program 
SYNOPSIS 

ftp [ -V ] [ -d ] [ -i ] [ -n ] [ -g ] [ host ] 

DESCRIPTION 

Ftp is the user interface to the ARPANET standard File Transfer Protocol. The program allows a user 
to transfer files to and from a remote network site. 

The client host with which ftp is to communicate may be specified on the command line. If this is 
done, ftp will immediately attempt to establish a connection to an FTP server on that host; otherwise, 
ftp will enter its command interpreter and await instructions firom the user. When ftp is awaiting com¬ 
mands from the user the prompt “fitp>” is provided to the user. The following commands are recog¬ 
nized by ftp: 

! [ command [ args ] ] 

Invoke an interactive shell on the local m^hine. If there are arguments, the first is taken to be 
a command to execute directly, with the rest of the arguments as its arguments. 

$ macro-name [ args ] 

Execute the macro macro-name that was defined with the macdef command. Arguments are 
passed to the macro unglobbed. 

account [ passwd ] 

Supply a supplemental password required by a remote system for access to resources once a 
login has been successfully completed. If no argument is included, the user will be prompted 
for an account password in a non-echoing input mode. 

append local-file [ remote-file ] 

Append a local file to a file on the remote machine. If remote-file is left unspecified, the local 
file name is used in naming the remote file after being altered by any ntrans or nmap setting. 
File transfer uses the current settings for type, format, mode, and structure. 

ascii Set the file transfer type to network ASCII. This is the default type. 

bell Arrange that a bell be sounded after each file transfer command is completed. 

binary Set the file transfer type to support binary image U’ansfer. 

bye Terminate the FTP session with the remote server and exit ftp. An end of file will also ter¬ 
minate the session and exit. 

case Toggle remote computer file name case mapping during mget commands. When case is on 
(default is off), remote computer file names with all letters in upper case are written in the 
local directory with the letters mapped to lower case. 

cd remote-directory 

Change the working directory on the remote machine to remote-directory. 

cdup Change the remote machine working directory to the parent of the current remote machine 
working directory. 

close Terminate the FTP session with the remote server, and return to the command interpreter. Any 
defined macros are erased. ( 

cr Toggle carriage return stripping during ascii type file retrieval. Records are denoted by a car¬ 
riage retum/linefeed sequence during ascii type file transfer. When cr is on (the default). 
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carriage returns are stripped from this sequence to conform with the UNIX single linefeed 
record delimiter. Records on non-UNIX remote systems may contain single linefeeds; when an 
ascii type transfer is made, these linefeeds may be distinguished from a record delimiter only 
when cr is off. 

delete remote-file 

Delete the file remote-file on the remote machine, 
debug [ debug-value ] 

Toggle debugging mode. If an optional debug-value is specified it is used to set the debugging 
level. When debugging is on, ftp prints each command sent to the remote machine, preceded 
by the string 

dir [ remote-directory ] [ local-file ] 

Print a listing of the directory contents in the directory, remote-directory, and, optionally, plac¬ 
ing the output in local-file. If no directory is specified, the current working directory on the 
remote machine is used. If no local file is specified, or local-file is -, output comes to the ter¬ 
minal. 

disconnect 

A synonym for close. 

form format 

Set the file transfer form to format. The default format is “file”, 
get remote-file [ local-file ] 

Retrieve the remote-file and store it on the local machine. If the local file name is not 
specified, it is given the same name it has on the remote machine, subject to alteration by the 
current case, ntrans, and nmap settings. The current settings for type, form, mode, and struc¬ 
ture are used while transferring the file. 

glob Toggle filename expansion for mdelete, mget and mput. If globbing is turned off with glob, 
the file name arguments are taken literally and not expanded. Globbing for mput is done as in 
csh(l). For mdelete and mget, each remote file name is expanded separately on the remote 
machine and the lists are not merged. Expansion of a directory name is likely to be different 
from expansion of the name of an ordinary file: the exact result depends on the foreign operat¬ 
ing system and ftp server, and can be previewed by doing ‘mis remote-files Note: mget 
and mput are not meant to transfer entire directory subtrees of files. That can be done by 
transferring a tar(l) archive of the subtree (in binary mode). 

hash Toggle hash-sign (“#”) printing for each data block transferred. The size of a data block is 
1024 bytes. 

help [ command ] 

Print an informative message about the meaning of command. If no argument is given, ftp 
prints a list of the known commands. 

led [ directory ] 

Change the working directory on the local machine. If no directory is specified, the user’s 
home directory is used. 

Is [ remote-directory ] [ local-file ] 

Print an abbreviated listing of the contents of a directory on the remote machine. If remote- 
directory is left unspecified, the current working directory is used. If no local file is specified, 
or if local-file is -, the output is sent to the terminal. 

maedef macro-name 

Define a macro. Subsequent lines are stored as the macro macro-name’, a null line (consecu¬ 
tive newline characters in a file or carriage returns from the terminal) terminates macro input 
mode. There is a limit of 16 macros and 4096 total characters in all defined macros. Macros 
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remain defined until a close command is executed. The macro processor interprets ’$’ and ’\’ 
as special characters. A ’$’ followed by a number (ot numbers) is replaced by the correspond¬ 
ing argument on the macro invocation command line. A ’$’ followed by an ’i’ signals that 
macro processor that the executing macro is to be looped. On the first pass ’$i’ is replaced by 
the first argument on the macro invocation command line, on the second pass it is replaced by 
the second argument, and so on. A V followed by any charact^ is replaced by that character. 
Use the V to prevent special treatment of the ’$’. 

mdelete [ remote-files ] 

Delete the remote-files on the remote machine. 

mdir remote-files local-file 

Like dir, except multiple remote files may be specified. If interactive prompting is on, ftp will 
prompt the user to verify that the last argument is indeed the target local file for receiving 
mdir output. 

mget remote-files 

Expand the remote-files on the remote machine and do a get for each file name thus produced. 
See glob for details on the filename expansion. Resulting file names will then be processed 
according to case, ntrans, and nmap settings. Files are transferred into the local working 
directory, which can be changed with ‘led directory’; new local directories can be created with 
‘! mkdir directory’. 

mkdir ^rectory-name 

Make a directory on the remote machine. 

mis remote-files local-file 

Like Is, except multiple remote files may be specified. If interactive prompting is on, ftp will 
prompt the user to verify that the last argument is indeed the target local file for receiving mis 
output 

mode [ mode-name ] 

Set the file transfer mode to mode-name. The default mode is “stream” mode. 

mput local-files 

Expand wild cards in the list of local files given as arguments and do a put for each file in the 
resulting list See glob for details of filename expansion. Resulting file names will then be 
processed according to ntrans and nmap settings. 

nmap [ inpattern outpattern ] 

Set or unset the filename mapping mechanism. If no arguments are specified, the filename 
mapping mechanism is unset If arguments are specified, remote filenames are mapped during 
mput commands and put commands issued without a specified remote target filename. If 
arguments are specified, local filenames are mapped during mget commands and get com¬ 
mands issued without a specified local target filename. This command is useful when connect¬ 
ing to a non-UNIX remote computer with different file naming conventions or practices. The 
mapping follows the pattern set by inpattern and outpattern. Inpattern is a template for 
incoming filenames (which may have already been processed according to the ntrans and case 
settings). Variable templating is accomplished by including the sequences ’$1’, ’$2’, ..., ’$9’ 
in inpattern. Use V to prevent this special treatment of the ’$’ character. All other characters 
are treated literally, and are used to determine the nmap inpattern variable values. For exma¬ 
ple, given inpattern $1.$2 and the remote file name "mydata.data", $1 would have the value 
"mydata", and $2 would have the value "data". The outpattern determines the resulting 
mapped filename. The sequences ’$1’, ’$2’, ...., ’$9’ are replaced by any value resulting from 
the inpattern template. The sequence ’$0’ is replace by the original filename. Additionally, 
the sequence '[seql,seq2Y is replaced by seql if seql is not a null string; otherwise it is 
replaced by seq2. For example, the command "nmap $1.$2.$3 [$l,$2].[$2,file]" would yield 
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the output filename "myfile.data" for input filenames "myfile.data" and "myfile.data.old", 
"myfile.file" for the input filename "myfile”, and "myfile.myfile" for the input filename 
".myfile”. Spaces may be included in outpattern, as in the example; nmap $1 Ised "s/ *$//" > 
$1 . Use the Y character to prevent special treatment of the and characters. 

ntrans [ inchars [ outchars ] ] 

Set or unset the filename character translation mechanism. If no arguments are specified, the 
filename character translation mechanism is unset. If arguments are specified, characters in 
remote filenames are translated during mput commands and put commands issued without a 
specified remote target filename. If arguments are specified, characters in local filenames are 
translated during mget commands and get commands issued without a specified local target 
filename. This command is useful when connecting to a non-UNIX remote computer with 
different file naming conventions or practices. Characters in a filename matching a character 
in inchars are replaced with the corresponding character in outchars. If the character’s posi¬ 
tion in inchars is longer than the length of outchars, the character is deleted fi-om the file 
name. 

open host [ port ] 

Establish a connection to the specified host FTP server. An optional port number may be sup¬ 
plied, in which cas&,ftp will attempt to contact an FTP server at that port. If the auto-login 
option is on (default), ftp will also attempt to automatically log the user in to the FTP server 
(see below). 

prompt Toggle interactive prompting. Interactive prompting occurs during multiple file transfers to 
allow the user to selectively retrieve or store files. If prompting is turned off (default is on), 
any mget or mput will transfer all files, and any mdelete will delete all files. 

proxy ftp-command 

Execute an ftp command on a secondary control connection. This command allows simultane¬ 
ous connection to two remote ftp servws for transferring files between the two servers. The 
first proxy command should be an open, to establish the secondary control connection. Enter 
the command "proxy ?" to see other ftp commands executable on the secondary connection. 
The following commands behave differently when prefaced by proxy: open will not define 
new macros during the auto-login process, close will not erase existing macro definitions, get 
and mget transfer files from the host on the primary control connection to the host on the 
secondary control connection, and put, mput, and append transfer files from the host on the 
secondary control connection to the host on the primary control connection. Third party file 
transfers depend upon support of the ftp protocol PASV command by the server on the secon¬ 
dary control connection. 

put local-file [ remote-file ] 

Store a local file on the remote machine. If remote-file is left unspecified, the local file name 
is used after processing according to any ntrans or nmap settings in naming the remote file. 
File transfer uses the current settings for type, format, mode, and structure. 

pwd Print the name of the current working directory on the remote machine, 
quit A synonym for bye. 
quote argl arg2 ... 

The arguments specified are sent, verbatim, to the remote FTP server. 

recv remote-file [ local-file ] 

A synonym for get. 

remotehelp [ command-name ] 

Request help from the remote FTP server. If a command-name is specified it is supplied to the 
server as well. 
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rename [from ] [ ro ] 

Rename the file/row on the remote machine, to the file to. 

reset Clear reply queue. This command re-synchronizes command/reply sequencing with the remote 
ftp server. Resynchronization may be neccesary following a violation of the ftp protocol by 
the remote server. 

rmdir directory-name 

Delete a directory on the remote machine. 

runique 

Toggle storing of files on the local syst^ with unique filenames. If a file already exists with 
a name equal to the target local filename for a get or mget command, a ".1" is appended to the 
name. If the resulting name matches another existing file, a ".2" is appended to the original 
name. If this process continues up to ”.99”, an otot message is printed, and the transfer does 
not take place. The generated unique filename will be reported. Note that runique will not 
affect local files generated from a shell command (see below). The default value is off. 

send local-file [ remote-file ] 

A synonym for put 

sendport 

Toggle the use of PORT commands. By default, ftp will attempt to use a PORT command 
when establishing a connection for each data transfer. The use of PORT commands can 
prevent delays when performing multiple file transfers. If the PORT command fails, ftp will 
use the default data port When the use of PORT commands is disabled, no attempt will be 
made to use PORT commands for each data transfer. This is useful for certain FTP implemen¬ 
tations which do ignore PORT commands but, incorrectly, indicate they’ve been accepted. 

status Show the current status of ftp. 
struct [ struct-name ] 

Set the file transfer structure to struct-name. By default “stream” structure is used. 

sunique 

Toggle storing of files on remote machine under unique file names. Remote ftp server must 
support ftp protocol STOU command for successful completion. The remote server will report 
unique name. Default value is off. 

tenex Set the file transfer type to that needed to talk to TENEX machines, 
trace Toggle packet tracing, 
type [ type-name ] 

Set the file transfer type to type-name. If no type is specified, the current type is printed. The 
default type is network ASCII. 

user user-name [ password ] [ account ] 

Identify yourself to the remote FTP server. If the password is not specified and the server 
requires it, ftp will prompt the user for it (after disabling local echo). If an account field is not 
specified, and the FTP server requires it, the user will be prompted for it. If an account field is 
specified, an account command will be relayed to the remote server after the login sequence is 
completed if the remote server did not require it for logging in. Unless ftp is invoked with 
“auto-login” disabled, this process is done automatically on initial connection to the FTP 
server. 

verbose Toggle verbose mode. In verbose mode, all responses from the FTP server are displayed to the 
user. In addition, if verbose is on, when a file transfer completes, statistics regarding the 
efficiency of the transfer are reported. By default, verbose is on. 

? [ command ] 
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A synonym for help. 

Command arguments which have embedded spaces may be quoted with quote (") marks. 

EUNICE NOTES 

This file is pertinent only to customers who have Wollongong’s WIN/TCP product 
ABORTING A FILE TRANSI?ER 

To abort a file transfer, use the terminal intarupt key (usually Ctrl-C). Sending transfers will be 
immediately halted. Receiving transfers will be halted by sending a ftp protocol ABOR command to 
the remote server, and discarding any further data received. The speed at which this is accomplished 
depends upon the remote server’s support for ABOR processing. If the remote server does not support 
the ABOR command, an ”ftp>" prompt will not appear until the remote server has completed sending 
the requested file. 


The terminal interrupt key sequence will be ignored when ftp has completed any local processing and is 
awaiting a rq)ly from the rwnote server. A long delay in this mode may result from the ABOR pro¬ 
cessing described above, or from unexpected behavior by the remote server, including violations of the 
ftp protocol. If the delay results from unexpected remote server behavior, the local ftp program must be 
killed by hand. 

FILE NAMING CONVENTIONS 

Files specified as arguments to ftp commands are processed according to the following rules. 

1) If the file name is specified, the stdin (for reading) or stdout (for writing) is used. 

2) If the first character of the file name is “I”, the remainder of the argument is interpreted as a 
shell command. Ftp then forks a shell, using popen(3) with the argument supplied, and reads 
(writes) from the stdout (stdin). If the shell command includes spaces, the argument must be 
quoted; e.g. “"I Is -It"”. A particularly useful example of this mechanism is: “dir Imore”. 

3) Failing the above checks, if “globbing” is enabled, local file names are expanded according to 
the rules used in the csh(l); c.f. the glob command. If the ftp command expects a single local 
file (.e.g. put), only the first filename generated by the "globbing" operation is used. 

4) For mget commands and get commands with unspecified local file names, the local filename is 
the remote filename, which may be altered by a case, ntrans, or nmap setting. The resulting 
filename may then be altered if runique is on. 

5) For mput commands and put commands with unspecified remote file names, the remote 
filename is the local filename, which may be altered by a ntrans or nmap setting. The result¬ 
ing filename may then be altered by the remote server if sunique is on. 


FILE TRANSFER PARAMETERS 

The FTP specification specifies many parameters which may affect a file transfer. The type may be one 
of “ascii”, “image” (binary), “ebcdic”, and “local byte size” (for PDP-lO’s and PDP-20’s mostly). 
Ftp supports the ascii and image types of file transfer, plus local byte size 8 for tenex mode transfers. 

Ftp supports only the default values for the remaining file transfer parameters: mode, form, and struct. 


OPTIONS 

Options may be specified at the command line, or to the command interpreter. 


The -v (verbose on) option forces ftp to show all responses from the remote server, as well as report on 
data transfer statistics. 


The -n option restrains ftp from attempting “auto-login” upon initial connection. If auto-login is 
enabled, ftp will check the .netrc (see below) file in the user’s home directory for an entry describing an 
account on the remote machine. If no entry exists, ftp will prompt for the remote machine login name 
(default is the user identity on the local machine), and, if necessary, prompt for a password and an 
account with which to login. 
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The -i option turns off interactive prompting during multiple file transfers. 

The -d option enables debugging. 

The -g option disables file name globbing. 

THE .netrc FILE 

The .netrc file contains login and initialization information used by the auto-login process. It resides in 
the user’s home directory. The following tokens are recognized; they may be separated by spaces, tabs, 
or new-lines: 

machine name 

Identify a remote machine name. The auto-login process searches the .netrc file for a machine 
token that matches the remote machine specified on the ftp command line or as an open com¬ 
mand argument. Once a match is made, the subsequent .netrc tokens are processed, stopping 
when the end of file is reached or another machine token is encountered. 

login name 

Identify a user on the remote machine. If this token is present, the auto-login process will ini¬ 
tiate a login using the specified name. 

password string 

Supply a password. If this token is present, the auto-login process will supply the specified 
string if the remote server requires a password as part of the login process. Note that if this 
token is present in the .netrc file, ftp will abort the auto-login process if the .netrc is readable 
by anyone besides the user. 

account string 

Supply an additional account password. If this token is present, the auto-login process will 
supply the specified string if the remote server requires an additional account password, or the 
auto-login process will initiate an ACCT command if it does not. 

macdef name 

Define a macro. This token functions like the ftp macdef command functions. A macro is 
defined with the specified name; its contents begin with the next .netrc line and continue until 
a null line (consecutive new-line characters) is encountered. If a macro named init is defined, 
it is automatically executed as the last step in the auto-login process. 

BUGS 

Correct execution of many commands depends upon proper behavior by the remote server. 

An error in the treatment of carriage returns in the 4.2BSD UNIX ascii-mode transfer code has been 
corrected. This correction may result in incorrect transfers of binary files to and from 4.2BSD servers 
using the ascii type. Avoid this problem by using the binary image type. 
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NOTE 

NOT PRESENT IN WOLLONGONG’S EUNICE! 


NAME 

gcore - get core images of running processes 

SYNOPSIS 

gcore process-id... 

DESCRIPTION 

Gcore creates a core image of each specified process, suitable for use with adb(l) or dbx(l). 

EUNICE NOTES 

Not implemented in EUNICE. 

FILES 

core.<process-id> core images 

BUGS 

Paging activity that occurs while gcore is running may cause the program to become confused. For 
best results, the desired processes should be stopped. 
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NAME 

gprof - display call graph profile data 
SYNOPSIS 

gprof [ options ] [ a.out [ gmon.out... ] ] 

DESCRIPTION 

gprof produces an execution profile of C, Pascal, or Fortran?? programs. The effect of called routines 
is incorporated in the profile of each caller. The profile data is taken from the call graph profile file 
(gmon.out default) which is created by programs which are compiled with the -pg option of cc, pc, and 
f77. That option also links in versions of the library routines which are compiled for profiling. The 
symbol table in the named object file (a.out default) is read and correlated with the call graph profile 
file. If more than one profile file is specified, the gprof output shows the sum of the profile information 
in the given profile files. 

First, a flat profile is given, similar to that provided by prof{\). This listing gives the total execution 
times and call counts for each of the functions in the program, sorted by decreasing time. 

Next, these times are propagated along the edges of the call graph. Cycles are discovered, and calls 
into a cycle are made to share the time of the cycle. A second listing shows the functions sorted 
according to the time they represent including the time of their call graph descendents. Below each 
function entry is shown its (direct) call graph children, and how their times are propagated to this func¬ 
tion. A similar display above the function shows how this function’s time and the time of its descen¬ 
dents is propagated to its (direct) call graph parents. 

Cycles are also shown, with an entry for the cycle as a whole and a listing of the members of the cycle 
and their contributions to the time and call counts of the cycle. 

The following options are available: 

-a suppresses the printing of statically declared functions. If this option is given, all relevant 
information about the static function {e.g., time samples, calls to other functions, calls from 
other functions) belongs to the function loaded just before the static function in the a.out file. 

-b supresses the printing of a description of each field in the profile. 

-c the static call graph of the program is discovered by a heuristic which examines the text space 
of the object file. Static-only parents or children are indicated with call counts of 0. 

~€ name 

suppresses the printing of the graph profile entry for routine name and all its descendants 
(unless they have other ancestors that aren’t suppressed). More than one -e option may be 
given. Only one name may be given with each -e option. 

-E name 

suppresses the printing of the graph profile entry for routine name (and its descendants) as -e, 
above, and also excludes the time spent in name (and its descendants) from the total and per¬ 
centage time computations. (For example, -E mcount -E mcleanup is the default.) 

-f name 

prints the graph profile entry of only the specified routine name and its descendants. More 
than one -f option may be given. Only one name may be given with each -f option. 

-F name 

prints the graph profile entry of only the routine name and its descendants (as -f, above) and 
also uses only the times of the printed routines in total time and percentage computations. 
More than one -F option may be given. Only one name may be given with each -F option. 
The -F option overrides the -E option. 

-s a profile file gmon.sum is produced which represents the sum of the profile information in all 
the specified profile files. This summary profile file may be given to subsequent executions of 
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gprof (probably also with a -^) to accumulate profile data across several runs of an a.out file. 

-z displays routines which have zero usage (as indicated by call counts and accumulated time). 
This is useful in conjunction with the -c option for discovering which routines were never 
called. 

FILES 

a.out the namelist and text space. 

gmon.oM dynamic call graph and profile. 

gmon.sum summarized dynamic call graph and profile. 

SEE ALSO 

monitor(3), profil(2), cc(l), prof(l) 

“gprof: A Call Graph Execution Profiler”, by Graham, S.L., Kessler, P.B., McKusick, M.K.; Proceed¬ 
ings of the SIGPLAN ’82 Symposium on Compiler Construction, SIGPLAN Notices, Vol. 17, No. 6, pp. 
120-126, June 1982. 

BUGS 

Beware of quantization errors. The granularity of the sampling is shown, but remains statistical at best. 
We assume that the time for each execution of a function can be expressed by the total time for the 
function divided by the number of times the function is called. Thus the time propagated along the call 
graph arcs to parents of that function is directly proportional to the num^r of times that arc is 
traversed. 

Parents which are not themselves profiled will have the time of their profiled children propagated to 
them, but they will appear to be spontaneously invoked in the call graph listing, and will not have their 
time propagated further. Similarly, signal catchers, even though profiled, will appear to be spontaneous 
(although for more obscure reasons). Any profiled children of signal catchers should have their times 
propagated properly, unless the signal catcher was invoked during the execution of the profiling routine, 
in which case dl is lost. 

The profiled program must call exit (2) or return normally for the profiling information to be saved in 
the gmon.out file. 


April 19, 1989 


The Wollongong Group 


2 



GRAPH (IG) 


UNIX Programmer’s Manual 


GRAPH (IG) 


NAME 

graph - draw a graph 

SYNOPSIS 

graph [ option ] ... 

DESCRIPTION 

Graph with no options takes pairs of numbers from the standard input as abscissas and ordinates of a 
graph. Successive points are connected by straight lines. The graph is encoded on the standard output 
for display by the plot{\G) filters. 

If the coordinates of a point are followed by a nonnumeric string, that string is printed as a label begin¬ 
ning on the point Labels may be surrounded with quotes in which case they may be empty or 
contain blanks and numbers; labels never contain newlines. 

The following options are recognized, each as a separate argument. 

-a Supply abscissas automatically (they are missing from the input); spacing is given by the next 
argument (default 1). A second optional argument is the starting point for automatic abscissas 
(default 0 or lower limit given by -x). 

-b Break (disconnect) the graph after each label in the input. 

-c Character string given by next argument is default label for each point 

-g Next argument is grid style, 0 no grid, 1 frame with ticks, 2 full grid (default). 

-1 Next argument is label for graph. 

-m Next argument is mode (style) of connecting lines: 0 disconnected, 1 connected (default). 
Some devices give distinguishable line styles for other small integers. 

-s Save screen, don’t erase before plotting. 

-X [ I ] If I is present, x axis is logarithmic. Next 1 (or 2) arguments are lower (and upper) x limits. 
Third argument, if present, is grid spacing on x axis. Normally these quantities are determined 
automatically. 

-y [ 1 ] Similarly for y. 

-h Next argument is fraction of space for height. 

“W Similarly for width. 

-r Next argument is fraction of space to move right before plotting. 

-u Similarly to move up before plotting. 

-t Transpose horizontal and vertical axes. (Option -x now applies to the vertical axis.) 

A legend indicating grid range is produced with a grid unless the -s option is present. 

If a specified lower limit exceeds the upper limit, the axis is reversed. 

SEE ALSO 

spline(lG), plot(lG) 

BUGS 

Graph stores all points internally and drops th(»e for which there isn’t room. 

Segments that run out of bounds are dropped, not windowed. 

Logarithmic axes may not be reversed. 
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NAME 

grep, egrep, fgrep - search a file for a pattern 
SYNOPSIS 

grep [ option ] ... expression [ file ] ... 
egrep [ option ] ... [ expression ] [ file ] ... 
fgrep [ option ]... [ strings ] [ file ] 

DESCRIPTION 

Commands of the grep family search the input files (standard input default) for lines matching a pattern. 
Normally, each line found is copied to the standard output. Grep patterns are limited regular expres¬ 
sions in the style of ex(\); it uses a compact nondeterministic algorithm. Egrep patterns are full regular 
expressions; it uses a fast deterministic algorithm that sometimes needs exponential space. Fgrep pat¬ 
terns are fixed strings; it is fast and compact The following options are recognized. 

-V All lines but those matching are printed. 

-X (Exact) only lines matched in their entirety are printed (fgrep only). 

-c Only a count of matching lines is printed. 

-1 The names of files with matching lines are listed (once) separated by newlines. 

-n Each line is preceded by its relative line number in the file. 

-b Each line is preceded by the block number on which it was found. This is sometimes useful in 

locating disk block numbers by context 

-i The case of letters is ignored in making comparisons — that is, upper and lower case are con¬ 
sidered identical. This applies to grep and fgrep only. 

-s Silent mode. Nothing is printed (except error messages). This is useful for checking the error 
status. 

-w The expression is searched for as a word (as if surrounded by V’ and V’, see ex{\).) (grep 
only) 

-e expression 

Same as a simple expression argument, but useful when the expression begins with a -. 

-f file The regular expression (egrep) or string list (fgrep) is taken from the file. 

In all cases the file name is shown if there is more than one input file. Care should be taken when 
using the characters $*['!() and \ in the ejq>ression as they are also meaningful to the Shell. It is 
safest to enclose the entire expression argument in single quotes ' '. 

Fgrep searches for lines that contain one of the (newline-separated) strings. 

Egrep accepts extended regular expressions. In the following description ‘character’ excludes newline: 

A \ followed by a single character other than newline matches that character. 

The character" matches the beginning of a line. 

The character $ matches the end of a line. 

A . (period) matches any character. 

A single character not otherwise endowed with special meaning matches that character. 

A string enclosed in brackets [] matches any single character from the string. Ranges of 
ASCII character codes may be abbreviated as in ‘a-zO-9’. A ] may occur only as the first 
character of the string. A literal - must be placed where it can’t be mistaken as a range indi¬ 
cator. 

A regular expression followed by an ♦ (asterisk) matches a sequence of 0 or more matches of 
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the regular expression. A regular expression followed by a + (plus) matches a sequence of 1 
or more matches of the regular expression. A regular expression followed by a ? (question 
mark) matches a sequence of 0 or 1 matches of the regular expression. 

Two regular expressions concatenated match a match of the first followed by a match of the 
second. 

Two regular expressions separated by I or newline match either a match for the first or a match 
for the second. 

A regular expression enclosed in parentheses matches a match for the regular expression. 

The order of precedence of operators at the same parenthesis level is [] then *+? then concatenation 
then I and newline. 

Ideally there should be only one grep, but we don’t know a single algorithm that spans a wide enough 
range of space-time tradeoffs. 

SEE ALSO 

ex(l), sed(l), sh(l) 

DIAGNOSTICS 

Exit status is 0 if any matches are found, 1 if none, 2 for syntax errors or inaccessible files. 

BUGS 

Lines are limited to 256 characters; longer lines are truncated. 
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NAME 

groups - show group memberships 

SYNOPSIS 

groups [user] 

DESCRIPTION 

The groups command shows the groups to which you or the optionally specified user belong. Each user 
belongs to a group specified in the password file /etc/passwd and possibly to other groups as specified in 
the file !etc!group. If you do not own a file but belong to the group which it is owned by then you are 
granted group access to the file. 

When a new file is created it is given the group of the containing directory. 

SEE ALSO 

setgroups(2) 

FILES 

/etc/passwd, /etc/group 

BUGS 

More groups should be allowed. 
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NAME 

head - give first few lines 
SYNOPSIS 

head [ -count ] [ file ... ] 

DESCRIPTION 

This filter gives the first count lines of each of the specified files, or of the standard input. If count is 
omitted it defaults to 10. 

SEE ALSO 

tail(l) 
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NOTE 


WOLLONGONG’S WIN/TCP PRODUCT 


NAME 

hostid - set or print identifier of current host system 

SYNOPSIS 

hostid [ identifier ] 

DESCRIPTION 

The hostid command prints the identifier of the current host in hexadecimal. This numeric value is 
expected to be unique across all hosts and is commonly set to the host’s Internet address. The super- 
user can set the hostid by giving a hexadecimal argument or the hostname; this is usually done in the 
startup script /etc/rc.local. 

EUNICE NOTES 

This file is pertinent only to customers who have Wollongong’s WIN/TCP product. 

SEE ALSO 

gethostid(2), sethostid(2) 
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NOTE 


WOLLONGONG’S WIN/TCP PRODUCT 


NAME 

hosmame - set or print name of current host system 
SYNOPSIS 

hostname [ nameofhost ] 

DESCRIPTION 

The hostname command prints the name of the current host, as given before the “login” prompt. The 
super-user can set the hostname by giving an argument; this is usually done in the startup script 
/etc/rc.local. 

EUNICE NOTES 

This file is pertinent only to customers who have Wollongong’s WIN/TCP product 
SEE ALSO 

gethosmame(2), sethosmame(2) 
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NAME 

ident - identify files 

SYNOPSIS 

ident file ... 

DESCRIPTION 

Ident searches the named files for all cxicurrences of the pattern $keyword:...$, where keyword is one of 

Author 

Date 

Header 

Locker 

Log 

Revision 

Source 

State 

These patterns are normally inserted automatically by the RCS command co (1), but can also be 
inserted manually. 

Ident works on text files as well as object files. For example, if the C program in file f.c contains 
char rcsidn = "SHeader: Header information $"; 
and f.c is compiled into f.o, then the command 
ident f.c f.o 
will print 
f.c: 

SHeader: Header information $ 
f.o: 

SHeaden Header information $ 

IDENTmCATION 

Author Walter F. Tichy, Purdue University, West Lafayette, IN, 47907. 

Revision Number 3.0 ; Release Date: 82712/04 . 

Copyright © 1982 by Walter F. Tichy. 

SEE ALSO 

ci (1), co (1), res (1), rcsdLff(l), rcsmeige (1), rlog (1), rcsfile (5). 

Walter F. Tichy, "Design, Implementation, and Evaluation of a Revision Control System," in Proceed¬ 
ings of the 6th International Conference on Software Engineerings IEEE, Tokyo, Sept 1982. 


April 20, 1989 


The Wollongong Group 


1 



INDENT(l) 


UNIX Programmer’s Manual 


INDENT(l) 


NAME 

indent - indent and format C program source 
SYNOPSIS 

indent [ input-file [ output-file ] ] [ -bad I -nbad ] [ -bap I -nbap ] [ -bbb I -nbbb ] [ -be I -nbc ] 
[ -bl I -br ] [ -cn ] [ -edn ] [ -cdb I -nedb ] [ -ce I -nee ] [ -ein ] [ -elin ] [ -dn ] [ -din ] 
[ -dj I -ndj ] [ -ei I -nei ] [ -fel I -nfel ] [ -in ] [ -ip I -nip ] [ -In ] [ -len ] [ -Ip I -nip ] 
[ -npro ] [ -pes I -npes ] [ -ps I -nps ] [ -psi I -npsl ] [ -se I -nse ] [ -sob I -nsob ] [ -st ] 
[ -troff ] [ -V I -nv ] 

DESCRIPTION 

Indent is a C program formatter. It refcvmats the C program in the input-file according to the switches. 
The switches which can be specified are described below. They may appear before or after the file 
names. 

NOTE: If you only specify an input-file, the formatting is done ‘in-place’, that is, the formatted file is 
written back into input-file and a backup copy of input-file is written in the current directory. If input- 
file is named ‘/blah/blah/file’, the backup file is named MeMAK. 

If output-file is specified, indent checks to make sure it is different from input-file. 

OPTIONS 

The options listed below control the formatting style imposed by indent. 

-bad,-nbad If -bad is specified, a blank line is forced after every block of declarations. Default: 
-nbad. 

-bap,-nbap If -bap is specified, a blank line is forced after every procedure body. Default: 

-nbap. 

-bbb,-nbbb If -bbb is specified, a blank line is forced before every block comment. Default: 

^ibbb. 


-bc,-nbc 

-br,-bl 


-cn 

-edn 

-cdb,-ncdb 


If -be is specified, then a newline is forced after each comma in a declaration, -nbc 
turns off this option. The default is -nbc. 

Specifying -bl lines up compound statements like this: 

ifU) 

{ 

code 

} 

Specifying -br (the default) makes them look like this: 
if (...) { 
code 

} 

The column in which comments on code start The default is 33. 

The column in which comments on declarations start. The default is for these com¬ 
ments to start in the same column as those on code. 

Enables (disables) the placement of comment delimiters on blank lines. With this 
option enabled, comments look like this: 

I* 

* this is a comment 
*1 

Rather than like this: 

/* this is a comment */ 

This only affects block comments, not comments to the right of code. The default is 
-cdb. 
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-ce.-^ce 

-cin 

-clw 

-dn 

-din 

-dj.-ndj 

-ei,-nei 

-fcl,-nfcl 

-in 

-ip.-nip 
-In 

-Ip,-nip 


-npro 

-pcs,-npcs 

-ps,-nps 

-psl,-npsl 


Enables (disables) forcing ‘else’s to cuddle up to the immediately preceding The 
default is -ce. 

Sets the continuation indent to be n. Continuation lines will be indented that far from 
the beginning of the first line of the statement. Parenthesized expressions have extra 
indentation added to indicate the nesting, unless -Ip is in effect, -ci defaults to the 
same value as -i. 

Causes case labels to be indented n tab stops to the right of the containing switch 
statement. -cliO.5 causes case labels to be indented half a tab stop. The default is 
-cliO. (This is the only option that takes a fractional argument.) 

Controls the placement of comments which are not to the right of code. Specifying 
-dl means that such comments are placed one indentation level to the left of code. 
The default -dO lines up these comments with the code. See the section on comment 
indentation below. 

Specifies the indentation, in character positions, from a declaration keyword to the 
following identifier. The default is -dil6. 

-dj left justifies declarations, -ndj indents declarations the same as code. The 
default is -ndj. 

Enables (disables) special else-if processing. If enabled, ifs following elses will have 
the same indentation as the preceding if statement. The default is -ei. 

Enables (disables) the formatting of comments that start in column 1. Often, com¬ 
ments whose leading T is in column 1 have been carefully hand formatted by the 
programmer. In such cases, -nfcl should be used. The default is -fcl. 

The number of spaces for one indentation level. The default is 8. 

Enables (disables) the indentation of parameter declarations from the left margin. 
The default is -ip. 

Maximum length of an output line. The default is 78. 

Lines up code surrounded by parenthesis in continuation lines. If a line has a left 
paren which is not closed on that line, then continuation lines will be lined up to start 
at the character position just after the left paren. For example, here is how a piece of 
continued code looks with -nip in effect: 

pi = first_procedure(second_procedure(p2, p3), 
third_procedure(p4, p5)); 

With -Ip in effect (the default) the code looks somewhat clearer: 
pi = first_procedure(second_procedure(p2, p3), 
third_procedure(p4, p5)); 

Inserting two more newlines we get 

pi = first_procedure(second_procedure(p2, 

p3), 

third_procedure(p4, 
p5)); 

Causes the profile files, ‘./.indent.pro’ and ‘”/.indent.pro’, to be ignored. 

If true (-i)cs) all procedure calls will have a space inserted between the name and the 
‘(’. The default is -npcs. 

If true (-ps) the pointer following operator *->’ will be surrounded by spaces on 
either side. The default is -nps. 

If true (-psl) the names of procedures being defined are placed in column 1 - their 
types, if any, will be left on the previous lines. The default is -psl. 
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-sc,-nsc Enables (disables) the placement of asterisks (‘*’s) at the left edge of all comments. 

The default is -«c. 


-sob,>nsob 
—st 

-Ttypencune 


-troff 


-v,-nv 


If -sob is specified, indent will swallow optional blank lines. You can use this to get 
rid of blank lines after declarations. Default: ^isob. 

Causes indent to take its input fi'om stdin, and put its output to stdout. 

Adds typename to the list of type keywords. Names accumulate: -T can be specified 
more than once. You need to specify all the typenames that appear in your program 
that are defined by typedefs - nothing will be harmed if you miss a few, but the pro¬ 
gram won’t be formatted as nicely as it should. This sounds like a painful thing to 
have to do, but it’s really a symptom of a problem in C: typedef causes a syntactic 
change in the language and indent can’t find all typedefs. 

Causes indent to format the program for processing by troff. It will produce a fancy 
listing in much the same spirit as vgrind. If the output file is not specified, the 
default is standard output, rather than formatting in place. 

-V turns on ‘verbose’ mode; -nv turns it off. When in verbose mode, indent reports 
when it splits one line of input into two or more lines of output, and gives some size 
statistics at completion. The default is -nv. 


FURTHER DESCRIPTION 

You may set up your own ‘profile’ of defaults to indent by creating a file called dndent.pro in either 
your login directory and/or the current directory and including whatever switches you like. Switches in 
‘.indentpro’ in the current directory override those in your login directory (with the exception of -T 
type definitions, which just accumulate). If indent is run and a profile file exists, then it is read to set 
up the program’s defaults. The switches should be separated by spaces, tabs or newlines. Switches on 
the command line, however, override profile switches. 

Comments 


'Box' comments. Indent assumes that any comment with a dash or star immediately after the start of 
comment (that is, */♦-’ or '/♦*’) is a comment surrounded by a box of stars. Each line of such a com¬ 
ment is left unchanged, except that its indentation may be adjusted to account for the change in inden¬ 
tation of the first line of the comment 

Straight text. All other comments are treated as straight text Indent fits as many words (separated by 
blanks, tabs, or newlines) on a line as possible. Blank lines break paragraphs. 

Comment indentation 


If a comment is on a line with code it is started in the ‘comment column’, which is set by the -cn com¬ 
mand line parameter. Otherwise, the comment is started at n indentation levels less than where code is 
currently being placed, where n is specified by the -dn command line parameter. If the code on a line 
extends past the comment column, the comment starts further to the right, and the right margin may be 
automatically extended in extreme cases. 

Preprocessor lines 

In general, indent leaves preprocessor lines alone. The only reformatting that it will do is to straighten 
up trailing comments. It leaves embedded comments alone. Conditional compilation (#ifdef...#endif) 
is recognized and indent attempts to correctly compensate for the syntactic peculiarities introduced. 

C syntax 

Indent understands a substantial amount about the syntax of C, but it has a ‘forgiving’ parser. It 
attempts to cope with the usual sorts of incomplete and misformed syntax. In particular, die use of 
macros like; 

#define forever for(;;) 
is handled properly. 
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FILES 

./.indent.pro profile file 

■’/.indent.pro profile file 

BUGS 

Indent has even more switches than Is. 

A common mistake that often causes grief is typing: 
indent *.c 

to the shell in an attempt to indent all the C programs in a directory. This is probably a bug, not a 
feature. 
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NAME 

install - install binaries 
SYNOPSIS 

install [ -c ] [ -m mode ] [ -o owner ] [ -g group ] [ -s ] binary destination 
DESCRIPTION 

Binary is moved (or copied if -c is specified) to destination . If destination already exists, it is removed 
before binary is moved. If the destination is a directory then binary is moved into the destination 
directory with its original file-name. 

The mode for Destination is set to 755; the ~m mode option may be used to specify a different mode. 
Destination is changed to owner root; the -o owner option may be used to specify a different owner. 
Destination is changed to group staff; the -g group option may be used to specify a different group. 

If the -s option is specified the binary is stripped after being installed. 

Install refuses to move a file onto itself. 

SEE ALSO 

chgrp(l), chmod(l), cp(l), mv(l), strip(l), chown(8) 
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NOTE 


NOT PRESENT IN WOLLONGONG’S EUNICE! 


NAME 

iostat - report I/O statistics 
SYNOPSIS 

iostat [ drives ] [ interval [ count ] ] 

DESCRIPTION 

Iostat iteratively reports the number of characters read and written to terminals per second, and, for 
each disk, the number of transfers per second, kilobytes transferred per second, and the milliseconds per 
average seek. It also gives the percentage of time the system has spent in user mode, in user mode run¬ 
ning low priority (niced) processes, in system mode, and idling. 

To compute this information, for each disk, seeks and data transfer completions and number of words 
transferred are counted; for terminals collectively, the number of input and ouQ)ut characters are 
counted. Also, each sixtieth of a second, the state of each disk is examined and a t^ly is made if the 
disk is active. From these numbers and given the transfer rates of the devices it is possible to deter¬ 
mine average seek times for each device. 

The optional interval argument causes iostat to report once each interval seconds. The first report is for 
all time since a reboot and each subsequent report is for the last interval only. 

The optional count argument restricts the number of reports. 

If more than 4 disk drives are configured in the system, iostat displays only the first 4 drives, with 
priority given to Massbus disk drives (i.e. if both Unibus and Massbus drives are present and the total 
number of drives exceeds 4, then some number of Unibus drives will not be displayed in favor of the 
Massbus drives). To force iostat to display specific drives, their names may be supplied on the com¬ 
mand line. 

EUNICE NOTES 

Not implemented in EUNICE. 

FILES 

/dev/kmem 

/vmunix 

SEE ALSO 

vmstat(l) 
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NAME 

join - relational database operator 
SYNOPSIS 

join [ options ] filel file2 
DESCRIPTION 

Join forms, on the standard ouq}ut, a join of the two relations specified by the lines of filel and file2. 
If filel is the standard input is used. 

Filel zjoA filel must be sorted in increasing ASCII collating sequence on the fields on which they are to 
be joined, normally the first in each line. 

There is one line in the output for each pair of lines in filel and filel that have identical join fields. 
The output line normally consists of the common field, then the rest of the line from filel , then the rest 
of the line from filel . 

Fields are normally separated by blank, tab or newline. In this case, multiple separators count as one, 
and leading separators are diseased. 

These options are recognized: 

-an In addition to the normal output, produce a line for each unpairable line in file n, where n is 1 
or 2. 

-e s Replace empty output fields by string s. 

-Jn m Join on the mth field of file n. If n is missing, use the mth field in each file. 

-o list Each output line comprises the fields specified in list, each element of which has the form n.m, 
where n is a file number and m is a field number. 

-tc Use character c as a separator (tab character). Every appearance of c in a line is significant. 
SEE ALSO 

sort(l), comm(l), awk(l) 

BUGS 

With default field separation, the collating sequence is that of sort -b\ with ~t, the sequence is that of a 
plain sort 

The conventions of join, sort, comm, uniq, look and awk{l) are wildly incongruous. 


April 20, 1989 


The Wollongong Group 


1 



KILL(l) 


UNIX Programmer’s Manual 


KILL(l) 


NAME 

kill - terminate a process with extreme prejudice 
SYNOPSIS 

kill [ -sig ] processid ... 
kill-1 

DESCRIPTION 

Kill sends the TERM (terminate, 15) signal to the specified processes. If a signal name or number pre¬ 
ceded by is given as first argument, that signal is sent instead of terminate (see «gvec(2)). The sig¬ 
nal names are listed by ‘kill -1’, and are as given in lusr/includelsignal.h, stripped of the common SIG 
prefix. 

The terminate signal will kill processes that do not catch the signal; ‘kill -9 ...’ is a sure kill, as the 
KILL (9) signal cannot be caught. By convention, if process number 0 is specified, all members in the 
process group (i.e. processes resulting from the current login) are signaled (but beware: this works only 
if you use 5/i(l); not if you use csh(l).) Negative process numbers also have special meanings; see 
kill (2) for details. 

The killed processes must belong to the current user unless he is the super-user. 

The process number of an asynchronous process started with is reported by the shell. Process 
numbers can also be found by using pj(l). Kill is a built-in to csh(l); it allows job specifiers of the 
form as arguments so process id’s are not as often used as kill arguments. See csh(l) for 

details. 

SEE ALSO 

csh(l), ps(l), kill(2), sigvec(2) 

BUGS 

A replacement for “kill O’’ for cj/i(l) users should be provided. 
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NAME 

last - indicate last logins of users and teletypes 
SYNOPSIS 

last [ -N ] [ name ... ] [ tty ... ] 

DESCRIPTION 

Last will look back in the wtmp file which records all logins and logouts for information about a user, a 
teletype or any group of users and teletypes. Arguments specify names of users or teletypes of interest. 
Names of teletypes may be given fiilly or abbreviated. Fot example ‘last 0’ is the same as ‘last ttyO’. 
If multiple arguments are givai, the informatics which applies to any of the arguments is printed. For 
example ‘last root console* would list all of "root’s" sessions as well as all sessions on the console ter¬ 
minal. Last will print the sessions of the specified users and teletypes, most recent first, indicating the 
times at which the session began, the duration of the session, and the teletype which the session took 
place on. If the session is still continuing or was cut short by a reboot, last so indicates. 

The pseudo-user reboot logs in at reboots of the system, thus 
last reboot 

will give an indication of mean time between reboot. 

Last with no arguments prints a record of all logins and logouts, in reverse order. The -N option limits 
the report to N lines. 

If last is interrupted, it indicates how far the search has progressed in wtny>. If interrupted with a quit 
signal (generated by a control-\) last indicates how far the search has progressed so far, and the search 
continues. 

FILES 

/usr/adm/wtmp login data base 

/usr/adm/shutdownlog which records shutdowns and reasons for same 
SEE ALSO 

wtmp(5), ac(8), lastcomm(l) 

AUTHOR 

Howard Katseff 
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NOTE 


NOT PRESENT IN WOLLONGONG’S EUNICE! 


NAME 

lastcomm - show last commands executed in reverse order 
SYNOPSIS 

lastcomm [ command name ] ... [user name]... [terminal name] ... 

DESCRIPTION 

Lastcomm gives information on previously executed commands. With no arguments, lastcomm prints 
information about all the commands recorded during the current accounting file’s lifetime. If called 
with arguments, only accounting entries with a matching command name, user name, or terminal name 
are printed. So, for example, 

lastcomm a.out root ttydO 

would produce a listing of all the executions of commands named a.out by user root on the terminal 
ttydO. 

For each process entry, the following are printed. 

The name of the user who ran the process. 

Flags, as accumulated by the accounting facilities in the system. 

The command name undo* which the process was called. 

The amount of cpu time used by the process (in seconds). 

The time the process exited. 

The flags are encoded as follows: “S” indicates the command was executed by the super-user, “F” 
indicates the command ran after a fork, but without a following exec, “C” indicates the command was 
run in PDP-11 compatibility mode (VAX only), **D” indicates the command terminated with the gen¬ 
eration of a core file, and “X” indicates the command was terminated with a signal. 

EUNICE NOTES 

Not implemented in EUNICE. 

FILES 

/usr/adm/acct 
SEE ALSO 

last(l), sigvec(2), acct(8), core(5) 


April 20, 1989 


The Wollongong Group 


1 



LD(1) 


UNIX Programmer’s Manual 


LD(1) 


NAME 

Id - link editor 
SYNOPSIS 

Id [ option ] ... file ... 

DESCRIPTION 

Ld combines sev»^ object programs into one, resolves external references, and searches libraries. In 
the simplest case sever^ object files are givoi, and Id combines them, producing an object module 
which can be either executed or become the input for a further Id run. (In the latter case, the -r option 
must be given to preserve the relocatitm bits.) The output of Id is left on a.out. This file is made exe¬ 
cutable only if no errors occuned during the load. 

The argument routines are concatenated in the order specified. The entry point of the output is the 
beginning of the first routine (unless the ~e option is specified). 

If any argument is a library, it is searched exactly once at the point it is encountered in the argument 
list Only those routines defining an unresolved external reference are loaded. If a routine from a 
library ref^nces another routine in the library, and the library has not been processed by ranlibil), the 
referenced routine must £^pear after the referencing routine in the library. Thus the order of programs 

within libraries may be important The first memb^ of a library should be a file named ‘_.SYMDEF’, 

which is understood to be a dictionary for the library as produced by ranlib{l); the dictionary is 
searched iteratively to satisfy as many references as possible. 

The symbols ‘_etext’, ‘_edata’ and ‘_end’ (‘etext*, ‘edata’ and ‘end’ in C) are reserved, and if referred 
to, are set to the first location above the program, the first location above initialized data, and the first 
location above all data respectively. It is erroneous to define these symbols. 

Ld understands several options. Except for -1, they should appear before the file names. 

~A This option specifies incremental loading, i.e. linking is to be done in a manner so that the 
resulting object may be read into an already executing program. The next argument is the 
name of a file whose symbol table will be taken as a basis on which to define additional sym¬ 
bols. Only newly linked material will be entered into the text and data portions of a.out, but 
the new symbol table will reflect every symbol defined before and after the incremental load. 
This argument must appear before any other object file in the argument list The -T option 
may be used as well, and will be taken to mean that the newly linked segment will commence 
at the corresponding address (which must be a multiple of 1024). The default value is the old 
value of _end. 

-D Take the next argument as a hexadecimal number and pad the data segment with zero bytes to 
the indicated length. 

-d Force definition of common storage even if the -r flag is present. 

-e The following argument is taken to be the name of the entry point of the loaded program; loca¬ 

tion 0 is the default. 

-Ldir Add dir to the list of directories in which libraries are searched for. Directories specified with 
-L are searched before the standard directories. 

-Ic This option is an abbreviation for the library name ‘libx.a’, where x is a string. Ld searches 
for libraries first in any directories specified with -L options, then in the standard directories 
‘/lib’, ‘/usr/lib’, and ‘/usr/local/lib’. A library is searched when its name is encountered, so the 
placement of a -1 is significant. 

-M produce a primitive load map, listing the names of the files which will be loaded. 

-N Do not make the text portion read only or sharable. (Use "magic number" 0407.) 

-n Arrange (by giving the output file a 0410 "magic number") that when the output file is exe¬ 
cuted, the text portion will be read-only and shared among all users executing the file. This 
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involves moving the data areas up to the first possible 1024 byte boundary following the end of 
the text. 

-0 The name argument after -o is used as the name of the Id output file, instead of a.out. 

-r Generate relocation bits in the output file so that it can be the subject of another Id run. This 

flag also prevents final definitions firom being given to common symbols, and suppresses the 
‘undefined symbol’ diagnostics. 

-S ‘Strip’ the output by removing all symbols except locals and globals. 

-s ‘Strip’ the output, that is, remove the symbol table and relocation bits to save space (but impair 

the usefulness of the debuggers). This information can also be removed by strip(l). 

-T The next argument is a hexadecimal number which sets the text segment origin. The default 
origin is 0. 

-t ("trace") Print the name of each file as it is processed. 

-u Take the following argument as a symbol and enter it as undefined in the symbol table. This 

is useful for loading wholly from a library, since initially the symbol table is empty and an 
unresolved reference is needed to force the loading of the first routine. 

-X Save local symbols except for those whose names begin with ‘L’. This option is used by cc{\) 
to discard internally-generated labels while retaining symbols local to routines. 

-x Do not presCTve local (non-.globl) symbols in the output symbol table; only enter external sym¬ 
bols. This option saves some space in the output file. 

-ysym Indicate each file in which sym appears, its type and whether the file defines or references it 
Many such options may be given to trace many symbols. (It is usually necessary to begin sym 
with an as external C, FORTRAN and Pascal variables begin with underscores.) 

-z Arrange for the process to be loaded on demand from the resulting executable file (413 format) 

rather than preloaded. This is the default Results in a 1024 byte header on the output file fol¬ 
lowed by a text and data segment each of which have size a multiple of 1024 bytes (being 
padded out with nulls in the file if necessary). With this format the first few BSS segment 
symbols may actually appear (from the output of size{l)) to live in the data segment; this to 
avoid wasting the space resulting from data segment size roundup. 

EUNICE NOTES 

EUNICE introduces additional options. 

-retrace 

Causes the loader to not insert traceback. This must be used when an image is to be installed. 
Refer to the VMS manuals for more information. This flag is specific to the vmsld(lW) pro¬ 
vided with EUNICE. 

-noshare 

This option cancels the default which loads the shareable C images and will cause all routines 
to be loaded out of the standard C library. This will produce an image which does not require 
the presence of the shareable C images. If this image is to be run on a VMS system without a 
EUNICE or UNIX license, read "REX Capabilities and Obligations" in The EUNICE BSD 
Reference Manual and obtain the proper license. This option is also important if you are 
linking code which manipulates the EUNICE runtime system (e.g. code with # include 
<eunice/eunice.h> in it). This flag is specific to the vmsld(l^ provided with EUNICE. 

-nopObufs 

Sets the NOPOBUFS flag in the VMS image header and sets the IMGI(X!NT to 250. This 
will keep RMS from intruding on PO space in those programs which are sensitive to the state 
of PO space. These are usually programs which do their own memory allocation and expect 
contiguous sbrks. Very few UNIX programs have this requirement (e.g adb and dd). Programs 
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using the malloc routines will not have any problems. Include /lib/prealloc.o for UNIX object 
files or /usr/libvms^realloc.obj for VMS object files in the load to keep EUNICE from intrud¬ 
ing on PO space. The internal EUNICE data structures will be preallocated. This flag is 
specific to the vmsld(lW) provided with EUNICE. 

-vSHRBLEIMAGENAME 

Includes the shareable image SHRBLEIMAGENAME in the load. This flag is specific to the 
vmsld(lW) provided with EUNICE. 

Note that vmsld does not reference the variables set up by the aliases vmsobj or unixobj. Use cc or f77 
for the load phase if these aliases are to be used or explicitly request fusr/eunlvmsld. See cc(l) and 
f77(l). 


FILES 


/lib/lib* .a 
/usr/lib/lib*.a 
/usr/local/lib/lib* .a 
a.out 


libraries 
more libraries 
still more libraries 
output file 


SEE ALSO 

as(l), ar(l). cc(l). ranUb(l), vmsld(lW), f77(l) 


BUGS 

There is no way to force data to be page aligned. Ld pads images which are to be demand loaded from 
the file system to the next page boundary to avoid a bug in the system. 
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NAME 

learn - computer aided instruction about UNIX 
SYNOPSIS 

learn [ -directory ] [ subject [ lesson ] ] 

DESCRIPTION 

L^arn gives Computer Aided Instruction courses and practice in the use of UNIX, the C Shell, and the 
BCTkeley text editors. To get started simply type learn. If you had used learn before and left your last 
session without completing a subject, the program will use information in $HOME/.leamrc to start you 
up in the same place you left off. Your first time through, learn will ask questions to find out what you 
want to do. Some questions may be bypassed by naming a subject, and more yet by naming a lesson. 
You may enter the lesson as a number that learn gave you in a previous session. If you do not know 
the lesson number, you may enter the lesson as a word, and learn will look for the first lesson contain¬ 
ing it. If the lesson is learn prompts for each lesson; this is useful for debugging. 

The subject ’s presently handled are 

files 

editor 

vi 

morefiles 

macros 

eqn 

C 

There are a few special commands. The command *bye’ terminates a learn session and ‘where’ tells 
you of your progress, with ‘where m’ telling you more. The command ‘again’ re-displays the text of 
the lesson and ‘again lesson' lets you review lesson. There is no way for learn to tell you the answers 
it expects in English, however, the command ‘hint’ prints the last part of the lesson script used to 
evaluate a response, while ‘hint m’ prints the whole lesson script This is useful for debugging lessons 
and might possibly give you an idea about what it expects. 

The -directory option allows one to exercise a script in a nonstandard place. 

FILES 

/usr/lib/leam subtree for all dependent directories and files 
/usr/tmp/pl* playpen directories 
$HOME/.leamrc startup information 

SEE ALSO 

csh(l), ex(l) 

B. W. Kemighan and M. E. Lesk, LEARN - Computer-Aided Instruction on UNIX 

BUGS 

The main strength of learn, that it asks the student to use the real UNIX, also makes possible baffling 
mistakes. It is helpful, especially for nonprogrammers, to have a UNIX initiate near at hand during the 
first sessions. 

Occasionally lessons are incorrect, sometimes because the local version of a command operates in a 
non-standard way. Occasionally a lesson script does not recognize all the different correct responses, in 
which case the ‘hint’ command may be useful. Such lessons may be skipped with the ‘skip’ command, 
but it takes some sophistication to recognize the situation. 

To find a lesson given as a word, learn does a simple fgrep{l) through the lessons. It is unclear 
whether this sort of subject indexing is better than none. 

Spawning a new shell is required for each of many user and internal functions. 
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The vi lessons are provided separately from the others. To use them see your system administrator. 
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NAME 


leave - remind you when you have to leave 


SYNOPSIS 

leave [ [+]hhmm ] 


DESCRIPTION 

Leave waits until the specified time, then reminds you that you have to leave. You are reminded 5 
minutes and 1 minute tefore the actual time, at the time, and every minute thereafter. When you log 
off, leave exits just before it would have printed the next message. 

The time of day is in the form hhmm' where hh is a time in hours (on a 12 or 24 hour clock). All 
times are converted to a 12 hour clock, and assumed to be in the next 12 hours. 

If the time is preceeded by *+’, the alarm will go off in hours and minutes from the current time. 

If no argument is given, leave prompts with "When do you have to leave?". A reply of newline causes 
leave to exit, otherwise the reply is assumed to be a time. This form is suitable for inclusion in a .login 
or .profile. 

Leave ignores interrupts, quits, and terminates. To get rid of it you should either log off or use “kill 
-9” giving its process id. 

SEE ALSO 

calendar(l) 


o 
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NAME 

lex - generator of lexical analysis programs 
SYNOPSIS 

lex [ -tvfta ] [ file ] ... 

DESCRIPTION 

Lex generates programs to be used in simple texical analyis of text The input files (standard input 
default) contain regular expressions to be searched for, and actions written in C to be executed when 
expressions are found. 

A C source program, ’lex.yy.c’ is generated, to be compiled thus: 
cc lex.yy.c -11 

This program, when run, copies unrecognized portions of the input to the output, and executes the asso¬ 
ciated C action for each regular expression that is recognized. 

The options have the following meanings. 

-t Place the result on the standard output instead of in file "lex.yy.c”. 

-V Print a one-line summary of statistics of the generated analyzer. 

-n Opposite of -v; -n is default. 

-f "Faster” compilation: don’t bother to pack the resulting tables; limited to small programs. 
EXAMPLE 

lex lexcommands 

would draw lex instructions from the file lexcommands, and place the output in lex.yy.c 


%% 

[A-Z] putchar(yytext[0]+'a'-'A'); 

[]+$ ; 

[ ]+ putchar(' y, 

is an example of a lex program that would be put into a lex command file. This program converts 
upper case to lower, removes blanks at the end of lines, and replaces multiple blanks by single blanks. 

SEE ALSO 

yacc(l), sed(l) 

M. E. Lesk and E. Schmidt, LEX - Lexical Analyzer Generator 
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NAME 

lint - a C program verifier 
SYNOPSIS 

lint [ --abchnpuvx ] file ... 

DESCRIPTION 

Lint attempts to detect features of the C program files which are likely to be bugs, or non-portable, or 
wasteful. It also checks the type usage of the program more strictly than the compilers. Among the 
things which are currently found are unreachable statements, loops not entered at the top, automatic 
variables declared and not used, and logical expressions whose value is constant. Moreover, the usage 
of functions is checked to find functions which return values in some places and not in others, functions 
called with varying numbers of arguments, and functions whose values are not used. 

By default, it is assumed that all the files are to be loaded together; they are checked for mutual compa¬ 
tibility. Function definitions for certain libraries are available to lint\ these libraries are referred to by a 
conventional name, such as ‘-Im’, in the style of W(l). Arguments ending in An arQ also treated as 
library files. To create lint libraries, use the -C option: 

lint -Cfoo files ... 

where files are the C sources of library foo. The result is a file llib-lfooAn in the correct library format 
suitable for linting programs v&mg foo. 

Any number of the options in the following list may be used. The -D, -U, and -I options of cc(l) are 
also recognized as separate arguments. 

p Attempt to check portability to the IBM and GCOS dialects of C. 

h Apply a number of heuristic tests to attempt to intuit bugs, improve style, and reduce waste. 

b Report break statements that cannot be reached. (This is not the default because, unfor¬ 
tunately, most lex and many yacc outputs produce dozens of such comments.) 

v Suppress complaints about unused arguments in functions. 

X Report variables referred to by extern declarations, but never used, 

a Report assignments of long values to int variables, 

c Complain about casts which have questionable portability. 

u Do not complain about functions and variables used and not defined, or defined and not used 
(this is suitable for running lint on a subset of files out of a larger program). 

n Do not check compatibility against the standard library. 

z Do not complain about structures that are never defined (e.g. using a structure pointer without 
knowing its contents.). 

Exit (2) and other functions which do not return are not understood; this causes various lies. 

Certain conventional comments in the C source will change the behavior of lint: 

/♦NOTREACHED*/ 

at appropriate points stops comments about unreachable code. 

/♦VARARGSnV 

suppresses the usual checking for variable numbers of arguments in the following function 
declaration. The data types of the first n arguments are checked; a missing n is taken to be 0. 

/♦NOSTRICT*/ 

shuts off strict type checking in the next expression. 

AARGSUSED*/ 

turns on the -v option for the next function. 
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/♦LINTLIBRARY*/ 

at the beginning of a file shuts off complaints about unused functions in this file. 


AUTHOR 

S.C. Johnson. Lint library construction implemented by Edward Wang. 


FILES 


/usr/lib/lint/lint[12] 

/usrAib/lint/ilib-lc.ln 

/usr/lib/lint/Uib-lc 

/usr/lib/lint/llib-poil.ln 

/usr/lib/lint/llib-port 

llib-l*.ln 


programs 

declarations for standard functions 
human readable version of above 
declarations for portable functions 
human readable ... 
library created with -C 


SEE ALSO 

cc(l) 

S. C. Johnson, Lint, a C Program Checker 


BUGS 

There are some things you just can’t get lint to shut up about 
/*NOSTRICT*/ is not implemented in the current version (alas). 
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NAME 

lisp - lisp interpreter 

SYNOPSIS 

lisp 

DESCRIPTION 

Lisp is a lisp interpreter for a dialect which closely resembles MTT’s Maclisp. This lisp, known as 
Franz Lisp, features an I/O facility which allows the user to change the input and output syntax, add 
macro characters, and maintain compatibility with upper-case only lisp systems; infinite precision 
integer arithmetic, and an error facility which allows the user to trap system errors in many different 
ways. Interpreted functions may be mixed with code compiled by liszt{\) and both may be debugged 
using the “Joseph Lister” trace package. A lisp containing compiled and interpreted code may be 
dumped into a file f(»' later use. 

There are too many functions to list here; one should refer to the manuals listed below. 

AUTHORS 

An early version was written by Jeff Levinsky, Mike Curry, and John Breedlove. Keith Sklower wrote 
and is maintaining the current version, with the assistance of John Foderaro. The garbage collector was 
implemented by Bill Rowan. 

FILES 

/usr/lib/lisp/trace.l Joseph Lister trace package 

/usr/lib/lispAoplevel.l top level read-eval-print loop 

SEE ALSO 

liszt(l), lxref(l) 

‘Franz Usp Manual, Version 1* by John K. Foderaro 
Macusp Manual 

BUGS 

The error system is in a state of flux and not all error messages are as informative as they could be. 
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NAME 

liszt - compile a Franz Lisp program 
SYNOPSIS 

liszt [ -mpqruwxCQST ] [ -e form ] [ -o objfile ] [ name ] 

DESCRIPTION 

Liszt takes a file whose names ends in M’ and compiles the FRanz Lisp code there leaving an object 
program on the file whose name is that of the stMirce with ‘.o’ substituted for ‘.1’. 

The following options are interpreted by liszt. 

-e Evaluate the given form before compilation begins. 

-m Compile a Maclisp file, by changing the readtable to conform to macusp syntax and includ¬ 
ing a macro-defined compatibility package. 

-o Put the object code in the specified file, rather than the default ‘.o’ file. 

-p places profiling code at the beginning of each non-local function. If the lisp system is also 

created with profiling in it, this allows function calling frequency to be determined (see 
profO).) 

-q Only print warning and error messages. Compilation statistics and notes on correct but unusual 
constructs will not be printed. 

-r place bootstrap code at the beginning of the object file, which when the object file is executed 
will cause a lisp system to be invoked and the object file fasl’ed in. 

-u Compile a UCI-lispfile, by changing the readtable to conform to UCI-Lisp syntax and including 
a macro-defined compatibility package. 

-w Suppress warning diagnostics. 

-X Create a lisp cross reference file with the same name as the source file but with ‘.x’ appended. 
The program frre/(l) reads this file and creates a human readable cross reference listing. 

-C put comments in the assembler output of the compiler. Useful for debugging the compiler. 

-Q Print compilation statistics and warn of strange constructs. This is the default 

-S Compile the named program and leave the assembler-language output on the corresponding file 

suffixed ‘.s’. This will also prevent the assembler language file from being assembled. 

-T send the assembler output to standard output 

If no source file is specified, then the compiler will run interactively. You will find yourself talking to 
the lispil) top-level command interpreter. You can compile a file by using the function liszt (an 
nlambda) with the same arguments as you use on the command line. For example to compile ‘foo’, a 
Maclisp file, you would use: 

(liszt -m foo) 


FILES 


Note that liszt supplies the “.1” extension for you. 


/usr/lib/lisp/machacks.l 

/usr/lib/lisp/syscall.l 

/usr/lib/lisp/ucifnc.l 


Maclisp compatibility package 
macro definitions of Unix system calls 
UCI Lisp compatibility package 


AUTHOR 

John Foderaro 


SEE ALSO 

lisp(l), lxref(l) 
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NAME 

In - make links 
SYNOPSIS 

In [ -s ] sourcename [ taigemame ] 

In [ -s ] sourcename 1 sourcename2 [ sourcenameS ... ] targetdirectory 
DESCRIPTION 

A link is a directory entry referring to a file; the same file (together with its size, all its protection infor¬ 
mation, etc.) may have several links to it There are two kinds of links: hard links and symbolic links. 

By default In makes hard links. A hard link to a file is indistinguishable firom the original directory 
entry; any changes to a file are effective independent of the name used to reference the file. Hard links 
may not span file systems and may not refer to directories. 

The -s option causes In to create symbolic links. A symbolic link contains the name of the file to 
which it is linked. The referenced file is used when an open(2) operation is performed on the link. A 
stat(2) on a symbolic link will return the linked-to file; an lstat(2) must be done to obtain information 
about the Unk. The readlink(2) call may be used to read the contents of a symbolic link. Symbolic 
links may span file systems and may refer to directories. 

Given one or two arguments. In creates a link to an existing file sourcename. If targetname is given, 
the link has that name; targetname may also be a directory in which to place the link; otherwise it is 
placed in the current directory. If only the directory is specified, the link will be made to the last com¬ 
ponent of sourcename. 

Given more than two arguments. In makes links in targetdirectory to all the named source files. The 
links made will have the same name as the files being linked to. 

EUNICE NOTES 

Hard links are not implemented in EUNICE BSD because of VMS restrictions. 

SEE ALSO 

rm(l), cp(l), mv(l), link(2), readlink(2), stat(2), symlink(2) 
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NAME 

lock - reserve a terminal 

SYNOPSIS 

lock [ -number ] 

DESCRIPTION 

Lock requests a password from the user, reads it again for verification and then it will normally not 
relinquish the terminal until the password is repeated. There are three other conditions under it will ter¬ 
minate: it accepts the password for root as an alternative to the one given by die user, it will timeout 
after some interval of time, and it may be killed by somebody with the appropiate permission. The 
default time limit is 15 minutes but it may be changed with the -number option where number is the 
time limit in minutes. 
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NOTE 


NOT PRESENT IN WOLLONGONG’S EUNICE! 


NAME 

logger - make entries in the system log 
SYNOPSIS 

logger [ -t tag ][ -p pri ][ -i ][ -f file ] [ message ... ] 

ARGUMENTS 
-t tag 

-p pn 

-i 

-tfile 
message 
DESCRIPTION 

^88^ provides a program interface to the syslog(3) system log module. 

A message can be given on the command line, which is logged immediately, or a file is read and each 
line is logged. 

EUNICE NOTES 

Not implemented in EUNICE. 

EXAMPLES 

logger System rebooted 

logger -p localO.notice -t HOSTIDM -f /dev/idmc 

SEE ALSO 

syslog(3) 


Mark every line in the log with the specified tag. 

Enter the message with the specified priority. The priority may be specified numerically 
or as a “facility .level” pair. For example, “-p locals .info” logs the message(s) as 
iVormational level in the locals facility. The default is “user.notice.” 

Log the process id of the loggCT process with each line. 

Log the specified file. 

The message to log; if not specified, the -4 file or standard input is logged. 


April 20, 1989 


The Wollongong Group 


1 



LOGIN(l) 


UNIX Programmer’s Manual 


LOGIN(l) 


NAME 

login - sign on 
SYNOPSIS 

login [ -p ] [ username ] 


DESCRIPTION 

The login command is used when a user initially signs on, or it may be used at any time to change 
from one user to another. The latter case is the one summarized above and described here. See “How 
to Get Started’’ for how to dial up initially. 

If login is invoked without an argument, it a^ for a user name, and, if appropriate, a password. Echo¬ 
ing is turned off (if possible) during the typing of the password, so it will not appear on the written 
record of the session. 

Aftor a successful login, accounting files are updated and the user is informed of the existence of mail. 
The message of the day is printed, as is the time of his last login. Both are suppressed if he has a 
“.hushlogin” file in his home directory; this is mostly used to make life easier for non-human users, 
such as uucp. 


Login initializes the user and group IDs and the woiidng directory, then executes a command interpreter 
(usually c.r/i(l)) according to specifications found in a password file. Argument 0 of the command 
interpreter is the name of the command interpreter with a leading dash (“-’’). 


Login also modifies the environment environO) with information specifying home directory, command 
interpreter, tenninal type (if available) and user name. The ‘-p’ argument causes the remainder of the 
environment to be preserved, otherwise any previous environment is discarded. 


If the file /etc/nologin exists, login prints its contents on the user’s terminal and exits. This is used by 
shutdown(S) to stop users logging in when the system is about to go down. 

Login is recognized by sh(l) and csh(l) and executed directly (without forking). 


FILES 


/etc/utmp 

/usr/admAvtmp 

/usr/spool/mail/* 

/etc/motd 

/etc/passwd 

/etc/nologin 

’ */.hushlogm 


accounting 

accounting 

mail 

message-of-the-day 
password file 
stops logins 
makes login quieter 


EUNICE NOTES 

login is available only from DCL. The -p and username options are not supported. 

SEE ALSO 

init(8), getty(8), mail(l), passwd(l), passwd(5), environ(7), shutdown(8), rlogin(lc) 

DIAGNOSTICS 

“Login incorrect,’’ if the name or the password is bad. 

“No Shell’’, “cannot open password file’’, “no directory’’: consult a programming counselor. 

BUGS 

An undocumented option, -r is used by the remote login sen'er, rlogind{SC) to force login to enter into 
an initial connection protocol, -h is used by telnetd(SC) and other servers to list the host from which 
the connection was received. 
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NAME 

look - find lines in a sorted list 
SYNOPSIS 

look [ -df ] string [ file ] 

DESCRIPTION 

Look consults a sorted file and prints all lines that begin with string. It uses binary search. 
The options d and f affect comparisons as in sort(\): 

d ‘Dictionary’ order: only letters, digits, tabs and blanks participate in comparisons, 
f Fold. Upper case letters compare equal to lower case. 

If no file is specified, lusrfdictlwords is assumed with collating sequence -df. 

FILES 

/usr/dict/words 

SEE ALSO 

sort(l), grep(l) 


LOOK(l) 
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NAME 

indxbib, lookbib - build inverted index for a bibliography, find references in a bibliography 

SYNOPSIS 

indxbib database ... 
lookbib [ -n ] database 

DESCWPTION 

Indxbib makes an inverted index to the named databases (or files) for use by lookbibiX) and refer(l). 
These files contain bibliographic references (or other kinds of information) separated by blank lines. 

A bibliographic ref^ence is a set of lines, constituting fields of bibliographic information. Each field 
starts on a line beginning with a followed by a key-letter, then a blank, and finally the contents 
of the field, which may continue until the next line starting with 

Indxbib is a shell script that calls /usr/lib/refer/mkey and /usr/lib/refer/inv. The first program, mkey, 
truncates words to 6 characters, and maps upp^ case to lower case. It also discards words shorter than 
3 characters, words among the 100 most common English words, and numbers (dates) < 1900 or > 
2000. These parameters can be changed; see jxtge 4 of the Refer document by Mike Lesk. The second 
program, inv, creates an entry file (.ia), a posting file (.ib), and a tag file (.ic), all in the working direc¬ 
tory. 

Lookbib uses an inverted index made by indxbib to find sets of bibliographic references. It reads key¬ 
words typed after the “>” prompt on the terminal, and retrieves records containing all these keywords. 
If nothing matches, nothing is returned except another “>” prompt. 

Lookbib will ask if you need instructions, and will print some brief information if you reply “y”. The 
“-n” flag turns off the prompt for instructions. 

It is possible to search multiple databases, as long as they have a common index made by indxbib. In 
that case, only the first argument given to indxbib is specified to lookbib. 

If lookbib does not find the index files (the .i[abc] files), it looks for a reference file with the same 
name as the argument, without the suffixes. It creates a file with a ’.ig’ suffix, suitable for use with 
fgrep. It then uses this fgrep file to find references. This method is simpler to use, but the .ig file is 
slower to use than the .i[abc] files, and does not allow the use of multiple reference files. 

FILES 

x.ia, x.ih, x.ic, where x is the first argument, or if these are not present, then x.ig, x 
SEE ALSO 

refer(l), addbib(l), sortbib(l), roffbib(l), lookbib(l) 

BUGS 

Probably all dates should be indexed, since many disciplines refer to literature written in the 1800s or 
earlier. 
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NAME 

lorder - find ordering relation for an object library 

SYNOPSIS 

lorder file ... 

DESCRIPTION 

The input is one or more object or library archive (see ar{\)) files. The standard output is a list of pairs 
of object file names, meaning that the first file of the pair refers to external identifiers defined in the 
second. The output may be processed by tsort{\) to find an ordering of a library suitable for one-pass 
access by W(l). 

This brash one-liner intends to build a new library from existing ‘.o’ files, 
ar cr library ' lorder *.0 I tsort' 

The need for lorder may be vitiated by use of ranlib{\), which converts an ordered archive into a ran¬ 
domly accessed library. 

FILES 

♦symref, *symdef 
nm(l), sed(l), sort(l), join(l) 

SEE ALSO 

tsort(l), ld(l), ar(l), ranlib(l) 

BUGS 

The names of object files, in and out of libraries, must end with ‘.o’; nonsense results otherwise. 
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NAME 

Ipq - spool queue examination program 
SYNOPSIS 

Ipq [ +[ n ] ] [ -1 ] [ -Pprinter ] [ job #...][ user... ] 

DESCRIPTION 

Ipq examines the spooling area used by /p^(8) for i»inting files on the line printer, and reports the 
status of the specified jobs or all jobs associated with a user. Ipq invoked without any arguments reports 
on any jobs currently in the queue. A -P flag may be used to specify a particular printer, otherwise the 
default line printer is used (ot the value of the PRINTER variable in the environment). If a + argument 
is supplied, Ipq displays the spool queue until it empties. Supplying a number immediately after the + 
sign indicates that Ipq should sleep n seconds in between scans of the queue. All other arguments sup¬ 
plied are interpreted as user names or job numbers to filter out only those jobs of interest 

For each job submitted (i.e. invocation of lpr(X)) Ipq reports the user’s name, current rank in the queue, 
the names of files comprising the job, the job identifi^ (a number which may be supplied to IprmiX) for 
removing a specific job), and the total size in bytes. The -1 option causes information about each of the 
files comprising the job to be printed. Normally, only as much information as will fit on one line is 
displayed. Job ordering is dependent on the algorithm used to scan the spooling directory and is sup¬ 
posed to be FIFO (First in First Out). File names comprising a job may be unavailable (when /pr(l) is 
used as a sink in a pipeline) in which case the file is indicated as ‘’(standard input)". 

If Ipq warns that there is no daemon present (i.e. due to some malfunction), the /pc (8) command can be 
used to restart the printer daemon. 


EUNICE NOTES 

Ipq displays only the VMS spool queue in the VMS style. 
None of the options listed are supported. 


FILES 


/etc/termcap 

/etc/printcap 

/usr/spool/* 

/usr/spool/*/cf* 

/usr/spool/*/lock 

/usr/eun/lpq 

/etc/eunic^dev.com 


for manipulating the screen for repeated display 

to determine printer characteristics 

the spooling directory, as determined from printcap 

control files specifying jobs 

the lock file to obtain the currently active job 

EUNICE BSD version of Ipq 

where PRINTER is assigned 


SEE ALSO 

Ipr(l), Iprm(l), lpc(8), lpd(8) 


BUGS 

Due to the dynamic nature of the information in the spooling directory Ipq may report unreliably. Out¬ 
put formatting is sensitive to the line length of the terminal; this can results in widely spaced columns. 

DIAGNOSTICS 

Unable to open various files. The lock file being malformed. Garbage files when there is no daemon 
active, but files in the spooling directory. 
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NAME 

Ipr, print - line printer spooler 
SYNOPSIS 

Ipr [ -m ] [ name ... ] 


DESCRIPTION 

Lpr causes the named files to be queued for printing. If no files are named, the standard input is read. 
The option -m causes notificaticHi via mail{\) to be s«it when the job completes. 

EUNICE NOTES 

The Ipr(l) command has no option for page length or number of lines per page as it is simply a ‘cat’ to 
the device /dev^rinter. It is important to remember that the concept of ‘paging’ known to pr(l), 
nrqff(l), and troff(l) is not known to Ipr(l). The VMS printer device driver defaults the number of 
lines per page to ‘62’. This default is different from standard 4.3 BSD UNIX in which the default is 
‘66’ lines pCT page. To change defaults for pr(l)^ nrojf(l) and troff(l) refer to the respective manual 
pages in the UMX User’s Reference Manual or the more complete documents in the UNIX User’s Sup¬ 
plementary Documents. 

There are two choices here: (a) alias lpr to ‘VMS PRINT/NOFEED’; (b) with pr(l), nroff(l) or troJf(l) 
specify the number of lines per page as ‘62’ to override the default of ‘66’ (see nroff(l), pr(l), troff(l)). 

For example: 


FILES 


the ‘1’ option to pr(l) ‘pr -162 arg...’ 

the ‘.pr macro to nroff(l), troff (1) *.pl -0.6’ 

(default is 11 inches, 4 lines is appx. 0.6 inches) 
lpr sends the files to the VMS line printer queue, if the printer is queued. 
None of the options listed for lpr are supported. 
print is not implemented. 

lusrilibllpd and /usrilib/lpf are not used by the EUNKTE BSD Ipr(l). 


/usr/spool/lpd/* 

/usr/lib/lpd 

/usr/lib/lpf 

/usr/eun/lpr 

/etc/eunice/dev.com 


spool area, see EUNICE NOTES 

printer daemon, see EUNICE NOTES 

filter to handle banners and underlining, see EUNICE NOTES 

EUNICE BSD version of lpr 

where PRINTER is assigned 


SEE ALSO 

pr(l), vlpr(l) 
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NAME 

Iprm - remove jobs from the line printer spooling queue 
SYNOPSIS 

Iprm [ ’■^printer ] [ - ] [ job # ... ] [ user ... ] 

DESCRIPTION 

Iprm will remove a job, or jobs, from a printer’s spool queue. Since the spooling directory is protected 
from users, using Iprm is normally the only method by which a usct may remove a job. 

Iprm without any arguments will delete the currently active job if it is owned by the user who invoked 
Iprm. 

If the - flag is specified, Iprm will remove all jobs which a user owns. If the super-user employs this 
flag, the spool queue will be emptied entirely. The owner is determined by the user’s login name and 
host name on the machine where the Ipr command was invoked. 

Specifying a user’s name, or list of user names, will cause Iprm to attempt to remove any jobs queued 
belonging to that user (or users). This form of invoking Iprm is useful only to the super-user. 

A user may dequeue an individual job by specifying its job number. This number may be obtained 
from the lpq{\) program, e.g. 

% Ipq -1 


1st: ken [job #013ucbarpa] 

(standard input) 100 bytes 

% Iprm 13 

Iprm will announce the names of any files it removes and is silent if there are no jobs in the queue 
which match the request list. 

Iprm will kill off an active daemon, if necessary, before removing any spooling files. If a daemon is 
killed, a new one is automatically restarted upon completion of file removes. 

The -P option may be usd to specify the queue associated with a specific printer (otherwise the default 
printer, or the value of the PRINTER variable in the environment is used). 

EUNICE NOTES 

None of the options listed for Iprm are supported. 

Iprm removes jobs from the VMS print queue. 


FILES 

/etc/printcap 

/usr/spool/* 

/usr/spool/*/lock 

/usr/eun/lprm 


printer characteristics file 
spooling directories 

lock file used to obtain the pid of the current 
daemon and the job number of the currently active job 
EUNICE BSD version of Iprm 


SEE ALSO 

lpr(l), Ipq(l) 


DIAGNOSTICS 

“Permission denied" if the user tries to remove files other than his own. 

BUGS 

Since there are race conditions possible in the update of the lock file, the currently active job may be 
incorrectly identified. 
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NOTE 


NOT PRESENT IN WOLLONGONG’S EUNICE! 


NAME 

Iptest - gen^te lineprinter ripple pattern 
SYNOPSIS 

Iptest [ length [ count ] ] 

DESCRIPTION 

Lptest writes the traditional "ripple test" pattern on standard output. In 96 lines, this pattern will print 
all 96 printable ASCII characters in each positicHi. While originally created to test printers, it is quite 
useful for testing terminals, driving terminal ports for debugging purposes, or any other task where a 
quick supply of random data is needed. 

The length argument specifies the output line length if the the default length of 79 is inappropriate. 

The count argument specifies the number of ouq)ut lines to be generated if the default count of 200 is 
inappropriate. Note that if count is to be specified, length must be also be specified. 

EUNICE NOTES 

Not implemented in EUNICE. 
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NAME 

Is - list contents of directory 
SYNOPSIS 

Is [ -acdfgilqrstulACLFR ] name ... 

DESCRIPTION 

For each directory argument. Is lists the contents of the directory; for each file argument. Is repeats its 
name and any otho- information requested. By default, the output is sorted alphabetically. When no 
argument is given, the current directory is listed. When several arguments are given, the arguments are 
first sorted appropriately, but file arguments are processed before directories and their contents. 

There are a large nurnb^ of options: 

-1 List in long format, giving mode, number of links, owner, size in bytes, and time of last 
modification for each file. (See below.) If the file is a special file the size field will instead 
contain the major and minor device numbers. If the file is a symbolic link the pathname of the 
linked-to file is printed preceded by 

-g Include the group ownership of the file in a long output 
-t Sort by time modified (latest first) instead of by name. 

-a List all entries; in the absence of this option, entries whose names begin with a period (.) are 

not listed. 

-s Give size in kilobytes of each file. 

-d If argument is a directory, list only its name; often used with -1 to get the status of a directory. 

-L If argument is a symbolic link, list the file or directory the link references rather than the link 

itself. 

-r Reverse the order of sort to get reverse alphabetic or oldest first as appropriate. 

-u Use time of last access instead of last modification for sorting (with the -t option) and/or print¬ 

ing (with the -1 option). 

-c Use time of file creation for sorting or printing. 

-i For each file, print the i-number in the first column of the report 

-f Force each argument to be interpreted as a directory and list the name found in each slot. This 

option turns off -t, -s, and -nr, and turns on -a; the order is the order in which entries 
appear in the directory. 

-F cause directories to be marked with a trailing sockets with a trailing *=’, symbolic links 
with a trailing and executable files with a trailing 

-R recursively list subdirectories encountered. 

-1 force one entry per line output format; this is the default when output is not to a terminal. 

-C force multi-column output; this is the default when output is to a terminal. 

-q force printing of non-graphic characters in file names as the character ‘?’; this is the default 
when output is to a terminal. 

The mode printed under the -I option contains 11 characters which are interpreted as follows: the first 
character is 

d if the entry is a directory; 
b if the entry is a block-type special file; 
c if the entry is a character-type special file; 

1 if the entry is a symbolic link; 
s if the entry is a socket, or 
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- if the entry is a plain file. 

The next 9 characters are interpreted as three sets of three bits each. The first set refers to owner per¬ 
missions; the next refers to permissions to others in the same user-group; and the last to all others. 
Within each set the three characters indicate permission respectively to read, to write, or to execute the 
file as a program. For a directory, ‘execute’ permission is interpreted to mean permission to search the 
directory. The permissions are indicated as follows; 

r if the file is readable; 
w if the file is writable; 

X if the file is executable; 

- if the indicated permissicxi is not granted. 

The group-execute permission character is given as s if the file has the set-group-id bit set; likewise the 
user-execute permission character is given as s if the file has the set-user-id bit set. 

The last character of the mode (normally ‘x’ or is t if the 1000 bit of the mode is on. See 
chmod{\) for the meaning of this mode. 

When the sizes of the files in a directory are listed, a total count of blocks, including indirect blocks is 
printed. 

EUNICE NOTES 

In EUNICE, Is -I will give "not found" on directories ot files for which one does not have "read" per¬ 
mission. Is without the option will list the directories or files. 

FILES 

/etc/passwd to get user id’s for ‘Is -1’. 

/etc/group to get group id’s for ‘Is -g’. 

BUGS 

Newline and tab are considered printing characters in file names. 

The ouQ)ut device is assumed to be 80 columns wide. 

The option setting based on whether the output is a teletype is undesirable as “Is -s” is much different 
than “Is -s I Ipr’’. On the other hand, not i)ing this setting would make old shell scripts which used Is 
almost certain losers. 
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NAME 

Ixref - lisp cross reference program 
SYNOPSIS 

Ixref [ -N ] xref-file ... [ -a source-file ... ] 

DESCRIPTION 

Lxref reads cross reference file(s) written by the lisp compiler liszt and prints a cross reference listing 
on the standard output Liszt will create a cross refaence file during compilation when it is given the 
-X switch. Cross reference files usually end in *.x* and consequently Ixref will append a ‘.x’ to the file 
names given if necessary. The first option to Ixref is a decimal integer, N, which sets the ignorelevel. If 
a function is called more than ignorelevel times, the cross reference listing will just print the number of 
calls instead of listing each one of them. The default for ignorelevel is 50. 

The -a option causes Ixref to put limited cross ref^nce information in the sources named. Ixref will 
scan the source and when it comes across a definition of a function (that is a line beginning with '(def 
it will preceed that line with a list of the functions which call this function, written as a comment pre- 
ceeded by ' . All existing lines beginning with ’ will be removed fi'om the file. If the source file 
contains a line beginning then this will disable this annotation process from this point on until a 
is seen (however, lines beginning with ’ will continue to be deleted). After the annoation is 
done, the original file food’ is renamed to ” %foo.r” and the new file with annotation is named food’ 

AUTHOR 

John Foderaro 

SEE ALSO 

lisp(l), liszt(l) 

BUGS 
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NAME 

m4 - macro processor 

SYNOPSIS 

m4 [ files ] 

DESCRIPTION 

M4 is a macro processor intended as a firont end for Ratfor, C, and other languages. Each of the argu¬ 
ment files is processed in order; if there are no arguments, or if an argument is the standard input is 
read. The processed text is written on the standard output 

Macro calls have the form 

name(aigl,arg2,.... argn) 

The *(’ niust immediately follow the name of the macro. If a defined macro name is not followed by a 
it is deemed to have no arguments. Leading unquoted blanks, tabs, and newlines are ignored while 
collecting arguments. Potential macro names consist of alphabetic letters, digits, and underscore 
where the first character is not a digit 

Left and right single quotes C 0 are used to quote strings. The value of a quoted string is the string 
stripped of the quotes. 

When a macro name is recognized, its arguments are collected by searching for a matching right 
parenthesis. Macro evaluation proceeds normally during the collection of the arguments, and any com¬ 
mas or right parentheses which happen to turn up within the value of a nested call are as effective as 
those in the original input text After argument collection, the value of the macro is pushed back onto 
the input stream and rescanned. 

M4 makes available the following built-in macros. They may be redefined, but once this is done the 
original meaning is lost. Their values are null unless otherwise stated. 

define The second argument is installed as the value of the macro whose name is the first argu¬ 
ment. Each occurrence of $n in the replacement text, where n is a digit, is replaced by the 
n-th argument. Argument 0 is the name of the macro; missing arguments are replaced by 
the null string. 

undefine removes the definition of the macro named in its argument 

ifdef If the first argument is defined, the value is the second argument, otherwise the third. If 
there is no third argument, the value is null. The word umx is predefined on UNIX ver¬ 
sions of m4. 

changequote 

Change quote characters to the first and second arguments. Changequote without argu¬ 
ments restores the original values (i.e .,''). 

M4 maintains 10 output streams, numbered 0-9. The final output is the concatenation of 
the streams in numerical order; initially stream 0 is the current stream. The divert macro 
changes the current output stream to its (digit-string) argument. Output diverted to a stream 
other than 0 through 9 is discarded. 

causes immediate output of text from diversions named as arguments, or all diversions if no 
argument. Text may be undiverted into another diversion. Undiverting discards the 
diverted text 

returns the value of the current output stream, 
reads and discards characters up to and including the next newline. 

has three or more arguments. If the first argument is the same string as the second, then 
the value is the third argument. If not, and if there are more than four arguments, the pro¬ 
cess is repeated with arguments 4, 5, 6 and 7. Otherwise, the value is either the fourth 
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string, or, if it is not present, null. 

incr returns the value of its argument incremented by 1. The value of the argument is calcu¬ 
lated by interpreting an initial digit-string as a decimal number. 

eval evaluates its argument as an arithmetic expression, using 32-bit arithmetic. Operators 
include /, %,' (exponentiation); relationals; parentheses. 

len returns the number of characters in its argument 

index returns the position in its first argument where the second argument begins (zero origin), or 
-1 if the second argument does not occur. 

substr returns a substring of its first argument The second argument is a zero origin number 
selecting the first character; the third argument indicates the length of the substring. A 
missing third argument is tak^ to be large enough to extend to the end of the first string. 

translit transliterates the characters in its first argument from the set given by the second argument 
to the set given by the third. No abbreviations are permitted. 

include returns the contents of the file named in the argument. 

sinclude is identical to include, except that it says nothing if the file is inaccessible. 

syscmd executes the UNIX command given in the first argument. No value is returned. 

maketemp fills in a string of XXXXX in its argument with the current process id. 

errprint prints its argument on the diagnostic ouq)ut file. 

dumpdef prints current names and definitions, for the named items, or for all if no arguments are 
given. 

SEE ALSO 

B. W. Kemighan and D. M. Ritchie, The M4 Macro Processor 
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NAME 

mail - send and receive mail 
SYNOPSIS 

mail [ -V ] [ -i ] [ -n ] [ -s subject ] [ user ... ] 

mail [ -V ] [ -i ] [ -n ] -f [ name ] 

mail [ -V ] [ -i ] [ -n ] -u user 

INTRODUCTION 

Mail is a intelligent mail processing system, which has a command syntax reminiscent of ed with lines 
replaced by messages. 

The -V flag puts mail into verbose mode; the details of delivery are displayed on the users terminal. 
The -i flag causes tty interrupt signals to be ignored. This is particularly useful when using mail on 
noisy phone lines. The -n flag inhibits the reading of /usr/lib/Mail.rc. 

Sending mail. To send a message to one or more people, mail can be invoked with arguments which 
are the names of people to whom the mail will be sent You are then expected to type in your mes¬ 
sage, followed by an EOT (control-Z) at the beginning of a line. A subject may be specified on the 
command line by using the s flag. (Only the first argument after the -s flag is used as a subject; be 
careful to quote subjects containing spaces.) The section below, labeled Replying to or originating mail, 
describes some features of mail available to help you compose your letter. 

Reading mail. In normal usage mail is given no arguments and checks your mail out of the post office, 
then prints out a one line header of each message thwe. The current message is initially the first mes¬ 
sage (numbered 1) and can be printed using the print command (which can be abbreviated p). You 
can move among the messages much as you move between lines in ed, with the commands *+’ and 
moving backwards and forwards, and simple numbers. 

Disposing of mail. After examining a message you can delete (d) the message or reply (r) to it Dele¬ 
tion causes the mail program to forget about the message. This is not irreversible; the message can be 
undeleted (u) by giving its number, or the mail session can be aborted by giving the exit (x) command. 
Deleted messages will, however, usually disappear never to be seen again. 

Specifying messages. Commands such as print and delete can be given a list of message numbers as 
arguments to apply to a number of messages at once. Thus “delete 1 2“ deletes messages 1 and 2, 
while “delete 1-5“ deletes messages 1 through 5. The special name addresses all messages, and 
“$“ addresses the last message; thus the command top which prints the first few lines of a message 
could be used in “tc^ *” to print the first few lines of ^ messages. 

Replying to or originating mail. You can use the reply command to set up a response to a message, 
sending it back to the person who it was from. Text you then type in, up to an end-of-file, defines the 
contents of the message. While you are composing a message, mail treats lines beginning with the 
character specially. For instance, typing “~m“ (alone on a line) will place a copy of the current 
message into the response right shifting it by a tabstop. Other escapes will set up subject fields, add 
and delete recipients to the message and allow you to escape to an e^tor to revise the message or to a 
shell to run some commands. (These options are given in the summary below.) 

Ending a mail processing session. You can end a mail session with the quit (q) command. Messages 
which have been examined go to your mbox file unless they have been deleted in which case they are 
discarded. Unexamined messages go back to the post office. The -f option causes mail to read in the 
contents of your mbox (or the specified file) for processing; when you quit, mail writes undeleted mes¬ 
sages back to this file. The -u flag is a short way of doing "mail -4 /usr/spool/mail/user". 

Personal and systemwide distribution lists. It is also possible to create a personal distribution lists so 
that, for instance, you can send mail to “cohorts” and have it go to a group of people. Such lists can 
be defined by placing a line like 

alias cohorts bill ozalp jkf mark kridIe@ucbcory 
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in the file .mailrc in your home directory. The current list of such aliases can be displayed with the 
alias (a) command in mail. System wide distribution lists can be created by editing /usr/lib/aliases, see 
aliases(5) and sendmail(S); these are kept in a diff^nt syntax. In mail you send, personal aliases will 
be expanded in mail sent to others so that they will be able to reply to the recipients. System wide 
aliases are not expanded when the mail is sent, but any reply returned to the machine will have the sys¬ 
tem wide alias expanded as all mail goes through sendmail. 

Network mail (ARPA, UUCP, Berknet) See mailaddr(7) for a description of network addresses. 

Mail has a number of options which can be set in the .mailrc file to alter its behavior; thus “set askcc” 
enables the “askcc” feature. (These options are summarized below.) 

SUMMARY 

(Adapted from the ‘Mail Reference Manual') 

Each command is typed on a line by itself, and may take arguments following the command word. The 
command need not be typed in its entirety - the fii^t command which matches the typed prefix is used. 
For commands which take message lists as arguments, if no message list is given, then the next mes¬ 
sage forward which satisfies the command’s requirements is used. If there are no messages forward of 
the current message, the search proceeds backwards, and if there are no good messages at all, mail 
types “No applicable messages’’ and aborts the command. 

- Goes to the previous message and pints it out. If given a numeric argument n, goes to 

the n-th previous message and prints it. 

? Prints a brief summary of commands. 

! Executes the UNIX shell command which follows. 

Print (P) Like print but also prints out ignored header fields. See also print , ignore and 

retain. 

(R) Reply to originator. Does not reply to other recipients of the original message. 

(T) Identical to the Print command. 

(a) With no arguments, prints out all currently-defined aliases. With one argument, prints 
out that alias. With more than one argument, creates an new or changes an on old alias. 

(alt) The alternates command is useful if you have accounts on several machines. It can 
be used to inform mail that the listed addresses are really you. When you reply to mes¬ 
sages, mail will not send a copy of the message to any of the addresses listed on the 
alternates list. If the alternates command is given with no argument, the current set of 
alternate names is displayed. 

(c) Changes the user’s working directory to that specified, if given. If no directory is 
given, then changes to the user’s login directory. 

(co) The copy command does the same thing that save does, except that it does not mark 
the messages it is used on for deletion when you quit. 

(d) Takes a list of messages as argument and marks them all as deleted. Deleted mes¬ 
sages will not be saved in mbox, nor will they be available for most other commands. 

(also dt) Deletes the current message and prints the next message. If there is no next 
message, mail says “at EOF.’’ 

(e) Takes a list of messages and points the text editor at each one in turn. On return 
from the editor, the message is read back in. 

(ex or x) Effects an immediate return to the Shell without modifying the user’s system 
mailbox, his mbox file, or his edit file in -f. 

file (fi) The same as folder. 


Reply 

Type 

alias 

alternates 

chdir 

copy 

delete 

dp 

edit 

exit 
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headers 

help 
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ignore 


mail 

mbox 

next 

preserve 

print 

quit 


reply 

respond 

retain 
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List the names of the folders in your folder directory. 

(fo) The folder command switches to a new mail file or folder. With no arguments, it 
tells you which file you are currentiy reading. If you give it an argument, it will write 
out changes (such as deletions) you have made in the current file and read in the new 
file. Some special conventions are recognized for the name. # means the previous file, % 
means your system mailbox, %user means user’s system mailbox, & means your "/mbox 
file, and +folder means a file in your folder directory. 

(f) Takes a list of messages and prints their message headers. 

(h) Lists the current range of headers, which is an 18 message group. If a “+” argument 
is given, then the next 18 message group is printed, and if a argument is given, the 
previous 18 message group is printed 

A synonym for ? 

(ho, also preserve) Takes a message list and marks each message therein to be saved in 
the user’s system mailbox instead of in mbox. Does not override the delete command. 

N.B.: Ignore has been superseded by retain. 

Add the list of header fields named to the ignored list. Header fields in the ignore list 
are not printed on your terminal when you print a message. This command is very handy 
for suppression of certain machine-generated header fields. The Type and Print com¬ 
mands can be used to print a message in its entirety, including ignored fields. If ignore is 
executed with no arguments, it lists the current set of ignored fields. 

(m) Takes as argument login names and distribution group names and sends mail to those 
people. 

Indicate that a list of messages be sent to mbox in your home directory when you quit. 
This is the default action for messages if you do not have the hold option set. 

(n like + or CR) Goes to the next message in sequence and types it With an argument 
list, types the next matching message. 

(pre) A synonym for hold. 

(p) Takes a message list and types out each message on the user’s terminal. 

(q) Terminates the session, saving all undeleted, unsaved messages in the user’s mbox file 
in his login directory, preserving all messages marked with hold or preserve or never 
referenced in his system mailbox, and removing all other messages fi’om his system mail¬ 
box. If new mail has arrived during the session, the message “You have new mail’’ is 
given. If given while editing a mailbox file with the -f flag, then the edit file is rewrit¬ 
ten. A return to the Shell is effected, unless the rewrite of edit file fails, in which case 
the user can escape with the exit command. 

(r) Takes a message list and sends mail to the sender and all recipients of the specified 
message. The default message must not be deleted. 

A synonym for reply. 

Add the list of header fields named to the retained list. Only the header fields in the 
retain list are shown on your terminal when you print a message. All other header fields 
are suppressed. The Type and Print commands can be used to print a message in its 
entirety. If retain is executed with no arguments, it lists the current set of retained 
fields. 
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save (s) Takes a message list and a filename and qjpends each message in turn to the end of 

the file. The filename in quotes, followed by the line count and character count is 
echoed on the us^’s terminal. 

set (se) With no arguments, prints all variable values. Otherwise, sets option. Arguments 

are of the form “optionsvalue” (no space before or after =) or “option.” 

shell (sh) Invokes an interactive version of the shell. 

size Takes a message list and prints out the size in characters of each message, 

source (so) The source command reads mail commands firom a file. 

top Takes a message list and prints the top few lines of each. The number of lines printed is 

controlled by the variable toplines and defaults to five. 

type (t) A synonym for print. 

unalias Takes a list of names defined by alias commands and discards the remembered groups of 
users. The group names no longer have any significance. 

undelete (u) Takes a message list and marks each message as not being deleted. 

unread (U) Takes a message list and marks each message as not having been read. 

unset Takes a list of option names and discards their remembered values; the inverse of set. 

visual (v) Takes a message list and invokes the display editor on each message. 

write (w) Similar to save, except that only the message body (without the header) is saved. 

Extremely useful for such tasks as sending and receiving source program text over the 
message system. 

xit (x) A synonym for exit. 

z Mail presents message headers in windowfuls as described under the headers command. 

You can move maiVs attention forward to the next window with the z command. Also, 
you can move to the previous window by using z-. 

Here is a summary of the tilde escapes, which are used when composing messages to perform special 
functions. Tilde escapes are only recognized at the beginning of lines. The name “tilde escape” is 
somewhat of a misnomer since the actual escape character can be set by the option escape. 

' Icommand Execute the indicated shell command, then return to the message. 

"b name ... Add the given names to the list of carbon copy recipients but do not make the names 
visible in the Cc: line ("blind" carbon copy). 

”c name ... Add the given names to the list of carbon copy recipients. 

"d Read the file “dead.letter” from your home directory into the message. 

"e Invoke the text editor on the message collected so far. After the editing session is 

finished, you may continue appending text to the message. 

“f messages Read the named messages into the message being sent If no messages are specified, 
read in the current message. 

“h Edit the message header fields by typing each one in turn and allowing the user to 

append text to the end or modify the field by using the current terminal erase and kill 
characters. 

“m messages Read the named messages into the message being sent, shifted right one tab. If no mes¬ 
sages are specified, read the current message. 

-p Print out the message collected so far, prefaced by the message header fields. 

-q Abort the message being sent, copying the message to “dead.letter” in your home 
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"r filename Read the named file into the message. 

"s string Cause the named string to become the current subject field. 

name ... Add the given names to the direct recipient list. 

”v Invoke an alternate editor (defined by the VISUAL option) on the message collected so 

far. Usually, the alternate editor will be a screen editor. After you quit the editor, you 
may resume appending text to the end of your message. 

"w filename Write the message onto the named file. 

" I command Pipe the message through the command as a filter. If the command gives no output or 
terminates abnormally, retain the original text of the message. The command fmt{\) is 
often used as command to rejustify the message. 

■""string Insert the string of text in the message prefaced by a single If you have changed the 
escape character, then you should double that character in order to send it 

Options are controlled via the set and unset commands. Options may be either binary, in which case it 
is only significant to see whether they are set or not; or string, in which case the actual value is of 
interest. The binary options include the following: 

append Causes messages saved in mbox to be appended to the end rather than prepended. 

(This is set in /usr/lib/Mail jc on version 7 systems.) 

ask Causes mail to prompt you for the subject of each message you send. If you respond 

with simply a newline, no subject field will be sent 

askcc Causes you to be prompted for additional carbon copy recipients at the end of each 

message. Responding with a newline indicates your satisfaction with the current list 

autoprint Causes the delete command to behave like dp - thus, after deleting a message, the 
next one will be typed automatically. 

debug Setting the binary option debug is the same as specifying -d on the command line 

and causes mail to output all sorts of information useful for debugging mail. 

dot The binary option dot causes mail to interpret a period alone on a line as the termina¬ 

tor of a message you are sending. Dot is set by default Use the unset dot command 
to override the default 

hold This option is used to hold messages in the system mailbox by default. 

ignore Causes interrupt signals from your terminal to be ignored and echoed as (a>’s. 

ignoreeof An option related to dot is ignoreeof which makes mail refuse to accept a control-z as 

the end of a message. Ignoreeof also applies to mail command mode. 

metoo Usually, when a group is expanded that contains the sender, the sender is removed 

fi-om the expansion. Setting this option causes the sender to be included in the group. 

nosave Normally, when you abort a message with two rubout, mail copies the partial letter 

to the file “dead.letter” in your home directory. Setting the binary option nosave 
prevents this. 

Replyall Reverses the sense of reply and Reply commands, 

quiet Suppresses the printing of the vereion when first invoked. 

verbose Setting the option verbose is the same as using the -v flag on the command line. 

When mail runs in verbose mode, the actual delivery of messages is displayed on he 
users terminal. 
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The following options have string values: 


EDITOR Pathname of the text editor to use in the edit command and ~e escape. If not 

defined, then a default editor is used. 

PAGER Pathname of the program to use in the more command or when crt variable is set. A 

default paginator is used if this option is not defined. 

SHELL Pathname of the shell to use in the ! command and the ”! escape. A default shell is 

used if this option is not defined. 

VISUAL Pathname of the text editor to use in the visual command and ” v escape. 

crt The valued option crt is used as a threshold to determine how long a message must 

be before PAGER is used to read it 

escape If defined, the first character of this option gives the character to use in the place of ~ 

to denote escapes. 

folder The name of the directory to use for storing folders of messages. If this name begins 

with a 7’, mail considers it to be an absolute pathname; otherwise, the folder direc¬ 
tory is found relative to your home directory. 

record If defined, gives the pathname of the file used to record all outgoing mail. If not 

defined, then outgoing mail is not so saved. 

toplines If defined, gives the number of lines of a message to be printed out with the top com¬ 

mand; normally, the first five lines are printed. 


FILES 

/usr/spool/mail/* 

"/mbox 

'/.mailrc 

/tmp/R# 

/usr/lib/Mail.help* 

/usr/lib/Mailjc 

Message* 


post office 
your old mail 

file giving initial mail commands 
temporary for editor escape 
help files 

system initialization file 
temporary for editing messages 


SEE ALSO 

binmail(l), fmt(l), newaliases(l), aliases(5), 
mailaddr(7), sendmail(8) 

‘The Mail Reference Manual’ 


BUGS 

There are many flags that are not documented here. Most are not useful to the general user. 
Usually, mail is just a link to Mail, which can be confusing. 

AUTHOR 

Kurt Shoens 


April 20, 1989 


The Wollongong Group 


7 



MAILINFO(IW) 


UNIX Programmer’s Manual 


MAILINFO(IW) 


NAME 

mailinfo - tells the user that UNIX mail has been received 

SYNOPSIS 

mailinfo 

DESCRIPTION 

Mailinfo is used to tell the user that he or she has received UNIX mail. Mailinfo does not provide 
information about VMS mail. 

EUNICE NOTES 

Mailinfo is a EUNICE BSD specific command. It is stored in /usr/eun. This command can be run as 
a part of LOGIN.COM to tell the user that he or she has received UNIX mail, without the user entering 
the EUNICE BSD environment. Enter the following line in LOGIN.COM: 

$RUN TWG$USR:[EUN]MAIUNFO. 
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NAME 

make - maintain program groups 
SYNOPSIS 

make [ -f makefile ] [ option ] ... file ... 

DESCRIPTION 

Make executes commands in makefile to update one or more target names. Name is typically a pro¬ 
gram. If no -f q)tion is present, ‘makefile’ and ‘Makefile’ are tried in order. If makefile is the 
standard input is taken. More than one -f option may appear. 

Make updates a target if it depends on prerequisite files that have been modified since the target was 
last modified, or if the target does not exist 

Makefile contains a sequence of entries that specify dependencies. The first line of an entry is a blank- 
separated list of targets, then a colon, then a list of prerequisite files. Text following a semicolon, and 
all following lines that begin with a tab, are shell commands to be executed to update the target If a 
name appears on the left of more than one ‘colon’ line, then it depends on all of the names on the right 
of the colon on those lines, but only one command sequence may be specified for it If a name appears 
on a line with a double colon :: then the command sequence following that line is performed only if the 
name is out of date with respect to the names to the right of the double colon, and is not affected by 
other double colon lines on which that name may appear. 

Two special forms of a name are recognized. A name like aib) means the file named b stored in the 
archive named a. A name like a((b)) means the file stored in archive a containing the entry point b. 

Sharp and newline surround comments. 

The following makefile says that ‘pgm’ depends on two files ‘a.o’ and ‘b.o’, and that they in turn 
depend on ‘.c’ files and a common file ‘incl’. 

pgm: a.o b.o 

cc a.o b.o -Im -o pgm 

a. o: incl a.c 

cc -c a.c 

b. o: incl b.c 

cc -c b.c 

Makefile entries of the form 
string 1 = string2 

are macro definitions. Subsequent appearances of $(stringl) or are replaced by string!. If 

stringl is a single character, the parentheses or braces are optional. 

Make infers prerequisites for files for which makefile gives no construction commands. For example, a 
‘.c’ file may be inferred as prerequisite for a ‘.o’ file and be compiled to produce the ‘.o’ file. Thus the 
preceding example can be done more briefly: 

pgm: a.o b.o 

cc a.o b.o -Im -o pgm 
a.o b.o: incl 

Prerequisites are inferred according to selected suffixes listed as the ‘prerequisites’ for the special name 
‘.SUFFIXES’; multiple lists accumulate; an empty list clears what came before. Order is significant; 
the first possible name for which both a file and a rule as described in the next paragraph exist is 
inferred. The default list is 

.SUFFIXES: .out .0 .c .e .r .f .y .1 .s .p 

The rule to create a file with suffix s2 that depends on a similarly named file with suffix si is specified 
as an entry for the ‘target’ sls2. In such an entry, the special macro $* stands for the target name with 
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suffix deleted, $<® for the full target name, $< for the complete list of prerequisites, and $? for the list 
of prerequisites that are out of date. For example, a rule for making optimized ‘.o’ files from ‘.c’ files 
is 

.c.o: ; cc -c -O -o $<a> $*.c 

Certain macros are used by the default inference rules to communicate optional arguments to any result¬ 
ing compilations. In particular, ‘CFLAGS* is used for cc(l) options, ‘FFLAGS’ for >77(1) options, 
‘PFLAGS’ for pc(l) options, and ‘LFLAGS’ and ‘YFLAGS’ for lex and yacc(l) options. In addition, 
the macro ‘MH..AGS’ is filled in with the initial command line options supplied to make. This 
simplifies maintaining a hierarchy of makefiles as one may then invoke make on makefiles in subdirec¬ 
tories and pass along useful options such as ~k. 

Anodic special macro is ‘VPATH’. The ‘VPATH’ macro should be set to a list of directories 
separated by colons. When make searches for a file as a result of a dependency relation, it will first 
search the current directory and then each of the directories on the ‘VPATH’ list If the file is found, 
the actual path to the file will be used, rather than just the filename. If ‘VPATH’ is not defined, then 
only the current directory is searched. 

One use for ‘VPATH’ is when one has several programs that compile from the same source. The 
source can be kept in one directory and each set of object files (along with a separate makefile) would 
be in a separate subdirectory. The ‘VPATH’ macro would point to the source directory in this case. 

Command lines are executed one at a time, each by its own shell. A line is printed when it is executed 
unless the special target ‘.SILENT’ is in makefile, or the first character of the command is 

Commands returning nonzero status (see intro 0)) cause make to terminate unless the special target 
‘.IGNORE’ is in makefile or the command begins with <:tabxhyphen>. 

Interrupt and quit cause the target to be deleted unless the target is a directory or depends on the spe¬ 
cial name ‘PRECIOUS’. 

Other options: 

-i Equivalent to the special entry ‘.IGNORE:’. 

-k When a command returns nonzero stahis, abandon work on the current entry, but continue on 
branches that do not depend on the current entry. 

-n Trace and print, but do not execute the commands needed to update the targets. 

-t Touch, i.e. update the modified date of targets, without executing any commands. 

-r Equivalent to an initial special entry ‘.SUFFIXES:’ with no list 

-s Equivalent to the special entry ‘.SILENT:’. 

FILES 

makefile. Makefile 
SEE ALSO 

sh(l), touch(l), n7(l), pc(l) 

S. I. Feldman Make - A Program for Maintaining Computer Programs 

BUGS 

Some commands return nonzero status inappropriately. Use A to overcome the difficulty. 

Commands thjd are directly executed by the shell, notably cd(l), are ineffectual across newlines in 
make. 

‘VPATH’ is intended to act like the System V ‘VPATH’ support, but there is no guarantee that it func¬ 
tions identically. 
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NAME 

man - find manual information by keywords; print out the manual 
SYNOPSIS 

man [ - ] [ -M path ] [ section ] title ... 
man -k keyword... 
man -f file... 


DESCRIPTION 

A/an is a program which gives information from the programmers manual. It can be asked for one line 
descriptions of commands specified by name, or for all commands whose description contains any of a 
set of keywords. It can also provide on-line access to the sections of the printed manual. 

When given the option -k and a set of keywords, man prints out a one line synopsis of each manual 
sections whose listing in the table of contents contains one of those keywords. 

When given the option -f and a list of file names, man attempts to locate manual sections related to 
those files, printing out the table of contents lines for those sections. 

When neither -k nor -f is specified, man formats a specified set of manual pages. If a section specifier 
is given man looks in the that section of the manual for the given titles. Section is either an Arabic sec¬ 
tion number (3 for instance), or one of the words “new,” “local,” “old,” or “public.” A section 
number may be followed by a single letter classifier (for instance, Ig, indicating a graphics program in 
section 1). If section is omitted, man searches all sections of the manual, giving preference to com¬ 
mands over subroutines in system libraries, and printing the first section it finds, if any. 

If the standard output is a teletype, or if the flag - is given, man pipes its output through more(l) with 
the option -s to crush out useless blank lines and to stop after each page on the screen. Hit a space to 
continue, a control-D to scroU 11 more lines when the output stops. 

Normally man checks in a standard location for manual information (/usr/man). This can be changed 
by supplying a search path (a la the shell) with the -M flag. The search path is a colon (':’) separated 
list of directories in which manual subdirectories may be found; e.g. “/usr/local:/usr/man”. If the 
environment variable ‘MANPATH’ is set, its value is used for the default path. If a search path is sup¬ 
plied with the -k or -4 options, it must be specified first. 

Man will look for the manual page in either of two forms, the nroff source or preformatted pages. If 
either version is available, the manual page will be displayed. If the preformatted version is available, 
and it has a more recent modify time than the nroff source, it will be promptly displayed. Otherwise, 
the manual page will be formatted with nroff and displayed. If the user has permission, the formatted 
manual page will be deposited in the proper place, so that later invocations of man will not need to for¬ 
mat the page again. 


FILES 

/usr/man 

/usr/man/man?/* 

/usr/man/cat?/* 

/usr/man/whatis 


standard manual area 
directories containing source for manuals 
directories containing preformatted pages 
keyword database 


SEE ALSO 

apropos(l), more(l), whereis(l), catman(8) 

BUGS 

The manual is supposed to be reproducible either on the phototypesetter or on a typewriter. However, 
on a typewriter some information is necessarily lost. 
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NAME 

merge - three-way file merge 
SYNOPSIS 

merge [ -p ] filel file2 fileS 
DESCRIPTION 

Merge incorporates all changes that lead form file! to fileS into filel. The result goes to std. output if -p 
is present, into filel otherwise. Merge is useful for combining separate changes to an original. Suppose 
filel is the original, and both filel and file3 are modifications of filel. Then merge combines both 
changes. 

An overlap occurs if both filel and fileS have changes in a common segment of lines. Merge prints 
how many overlaps occurred, and includes both alternatives in the result. The alternatives are delimited 
as follows: 

«««< filel 
lines in filel 


lines in file3 
»»»> files 

If there are overlaps, the user should edit the result and delete one of the alternatives. 
IDENTinCATION 

Author: Walter F. Tichy, Purdue University, West Lafayette, IN, 47907. 

Revision Numben 3.0 ; Release Date: %2I\\I15 . 

Copyright © 1982 by Walter F. Tichy. 

SEE ALSO 

diffS (1), diff (1), rcsmerge (1), co (1). 
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NAME 

mesg - permit or deny messages 

SYNOPSIS 

mesg [ n ] [ y ] 

DESCRIPTION 

Mesg with argument n forbids messages via write and talk{\) by revoking non-user write permission on 
the user’s terminal. Mesg with argument y reinstates permission. All by itself, mesg reports the cuirent 
state without changing it 

FILES 

/dev/tty* 

SEE ALSO 

write(l), talk(l) 

DIAGNOSTICS 

Exit status is 0 if messages are receivable, 1 if not, 2 on error. 
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NAME 

mkdir - make a directory 

SYNOPSIS 

mkdir dimame ... 

DESCRIPTION 

Mkdir creates specified directories in mode 111. Standard entries, for the directory itself, and 
for its parent, are made automatically. 

Mkdir requires write permission in the parent directory. 

SEE ALSO 

rmdir(l) 
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NAME 

mkstr - create an error message file by massaging C source 
SYNOPSIS 

mkstr [ - ] messagefile prefix file ... 

DESCRIPTION 

Mkstr is used to create files of error messages. Its use can make programs with large numbers of error 
diagnostics much smaller, and reduce system overhead in running the program as the error messages do 
not have to be constantly swapped in and out 

Mkstr will process each of the specified files, placing a massaged version of the input file in a file 
whose name consists of the specified prefix and the original name. A typical usage of mkstr would be 

mkstr pistrings xx *.c 

This command would cause all the error messages from the C source files in the current directory to be 
placed in the file pistrings and processed copies of the source for these files to be placed in files whose 
names are prefixed with xx. 

To process the error messages in the source to the message file mkstr keys on the string ‘error("’ in the 
input stream. Each time it occurs, the C string starting at the is placed in the message file followed 
by a null character and a new-line character, the null character terminates the message so it can be 
easily used when retrieved, the new-line character makes it possible to sensibly cat the error message 
file to see its contents. The massaged copy of the input file then contains a Iseek pointer into the file 
which can be used to retrieve the message, i.e.: 

char efilname[] = 7usr/lib/pi_strings"; 

int efil s -1; 

error(al, a2, a3, a4) 

{ 

char buf[256]; 

if (efil < 0) { 

efil = open(efilname, 0); 
if (efil < 0) { 

oops: 

perror(efilname); 

exit(l); 

} 

} 

if (lseek(efil, (long) al, 0) II read(efil, buf, 256) <= 0) 
goto oops; 

printf(buf, a2, a3, a4); 

} 

The optional - causes the error messages to be placed at the end of the specified message file for 
recompiling part of a large mkstr ed program. 

SEE ALSO 

lseek(2), xstr(l) 
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NAME 

more, page - file perusal filter for crt viewing 
SYNOPSIS 

more [ -cdflsu ] [ -n ] [ +linenwnber ] [ +lpattem ] [ name ... ] 
page more options 
DESCRIPTION 

More is a filter which allows examination of a continuous text one screenful at a time on a soft-copy 
terminal. It normally pauses after each screenful, printing -More- at the bottom of the screen. If the 
user then types a carriage return, one more line is displayed. If the user hits a space, another screenful 
is displayed. Other possibilities are enumerated later. 

The command line options are: 

-n An integ^ which is the size (in lines) of the window which more will use instead of the 
default. 

-c More will draw each page by beginning at the top of the screen and erasing each line just 
before it draws on it. This avoids scrolling the screen, making it easier to read while more is 
writing. This option will be ignored if the terminal does not have the ability to clear to the 
end of a line. 

-d More will prompt the user with the message "Press space to continue, 'q' to quit" at the end 
of each screenful, and will respond to subsequent illegal user input by printing "Press 'h' for 
instructions." instead of ringing the beU. This is useful if ?nore is being used as a filter in 
some setting, such as a class, where many users may be unsophisticated. 

-f This causes more to count logical, rather than screen lines. That is, long lines are not folded. 
This option is recommended if nroff output is being piped through ul, since the latter may gen¬ 
erate escape sequences. These escape sequences contain characters which would ordinarily 
occupy screen positions, but which do not print when they are sent to the terminal as part of an 
escape sequence. Thus more may think that lines are longer than they actually are, and fold 
lines erroneously. 

-1 Do not treat 'L (form feed) specially. If this option is not given, more will pause after any line 
that contains a "L, as if the end of a ^reenful had been reached. Also, if a file begins with a 
form feed, the screen will be cleared before the file is printed. 

-s Squeeze multiple blank lines from the output, producing only one blank line. Especially help¬ 
ful when viewing nroff output, this option maximizes the useful information present on the 
screen. 

-u Normally, more will handle underlining such as produced by nroff in a manner appropriate to 
the particular terminal: if the terminal can perform underlining or has a stand-out mode, more 
will output appropriate escape sequences to enable underlining or stand-out mode for under¬ 
lined information in the source file. The -u option suppresses this processing. 

+linenumber 

Start up at linenumber, 

+lpattern 

Start up two lines before the line containing the regular expression pattern. 

If the program is invoked as page, then the screen is cleared before each screenful is printed (but only 
if a full screenful is being printed), and k - \ rather than k - 2 lines are printed in each screenful, 
where k is the number of lines the terminal can display. 

More looks in the file /etcitermcap to determine terminal characteristics, and to determine the default 
window size. On a terminal capable of displaying 24 lines, the default window size is 22 lines. 
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More looks in the environment variable MORE to pre-set any flags desired. For example, if you prefer 
to view files using the -c mode of operation, the csh command setenv MORE -c or the sh command 
sequence MORE=’-c’ ; export MORE would cause all invocations of more , including invocations by 
programs such as man and msgs , to use this mode. Normally, the user will place the command 
sequence which sets up the MORE environment variable in the .cshrc or .profile file. 

If more is reading from a file, rather than a pipe, then a percentage is displayed along with the -More- 
prompt This gives the fraction of the file (in characters, not lines) that h^ been read so far. 

Other sequences which may be typed when more pauses, and their effects, are as follows (z is an 
optional integer argument defaulting to 1): 

i <space> 

display i more lines, (or another screenful if no argument is given) 

"D display 11 more lines (a “scroll”). If / is given, then the scroll size is set to i. 
d same as 'D (control-D) 

iz same as typing a space except that z, if present, becomes the new window size. 

z s skip z lines and print a screenful of lines 

z f skip z screenfuls and print a screenful of lines 

zb skip back z screenfuls and print a screenful of lines 

z"B same as b 

q or Q Exit from more. 

- Display the current line number. 

V Start up the editor vz at the current line, 

h Help command; give a description of all the more commands. 

z/expr search for the z-th occurrence of the regular expression expr. If there are less than z 

occurrences of ejqjr, and the input is a file (rather than a pipe), then the position in the file 

remains unchanged. Otherwise, a screenful is displayed, starting two lines before the place 
where the expression was found. The user’s erase and kill characters may be used to edit the 
regular expression. Erasing back past the first column cancels the search command. 

z n search for the z -th occurrence of the last regular expression entered. 

(single quote) Go to the point from which the last search started. If no search has been per¬ 
formed in the current file, this command goes back to the beginning of the file. 

[command 

invoke a shell with command. The characters and ‘!’ in "command" are replaced with the 
current file name and the previous shell command respectively. If there is no current file 
name, *%’ is not expanded. The sequences ’\%" and "\!" are replaced by "%" and "!" respec¬ 
tively. 

z :n skip to the z -th next file given in the command line (skips to last file if n doesn’t make sense) 

z:p skip to the z-th previous file given in the command line. If this command is given in the mid¬ 

dle of printing out a file, then more goes back to the beginning of the file. If z doesn’t make 
sense, more skips back to the first file. If more is not reading from a file, the bell is rung and 
nothing else happens. 

:f display the current file name and line number. 

:q or :Q exit from more (same as q or Q). 
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(dot) repeat the previous command. 

The commands take effect immediately, i.e., it is not necessary to type a carriage return. Up to the 
time when the command character itself is given, the user may hit the line kill character to cancel the 
numerical argument being formed. In addition, the user may hit the erase character to redisplay the -- 
More“(xx%) message. 

At any time when ouQ)ut is being sent to the terminal, the user can hit the quit key (normally con- 
trol-\). More will stop sending output, and will display the usual -More- prompt. The user may then 
enter one of the above commands in the normal manner. Unfortunately, some output is lost when this 
is done, due to the fact that any characters waiting in the terminal’s output queue are flushed when the 
quit signal occurs. 

The terminal is set to noecho mode by this program so that the output can be continuous. What you 
type will thus not show on your terminal, except for the / and ! commands. 

If the standard output is not a teletype, then more acts just like cat, except that a header is printed 
before each file (if there is more than one). 

A sample usage of more in previewing nroff output would be 

nroff -ms +2 doc.n I more -s 

FILES 

/etc/termcap Terminal data base 

/usr/lib/more.helpHelp file 

SEE ALSO 

csh(l), man(l), msgs(l), script(l), sh(l), environ(7) 

BUGS 

Skipping backwards is too slow on large files. 
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NAME 

mset - retrieve ASCII to IBM 3270 keyboard map 

SYNOPSIS 

mset 

DESCRIPTION 

Mset retrieves mapping information for the ASCII keyboard to IBM 3270 terminal special functions. 
Normally, these mappings are found in Ietclmap3270 (see map3270{5)). This information is used by 
the tn3270 command (see tn3270{\)). 

Mset can be used store the mapping information in the process environment in order to avoid scanning 
Ietclmap3270 each time tn3270 is invoked. To do this, place the following command in your .login 
file: 

set noglob; setenv MAP3270 "'mset'”; unset noglob 

Mset first determines the user’s terminal type from the environment variable TERM. Normally mset 
then uses the file Ietclmap3270 to find die keyboard mapping for that terminal. However, if the 
environment variable MAP3270 exists and contains the entry for the specified terminal, then that 
definition is used. If the value of MAP3270 begins with a slash (7’) then it is assumed to be the full 
pathname of an alternate mapping file and that file is searched first In any case, if the mapping for the 
terminal is not found in the environment, nor in an alternate map file, nor in the standard map file, then 
the same search is performed for an entry for a terminal type of unknown. If that search also fails, then 
a default mapping is used. 

FILES 

/etc/map3270 keyboard mapping for known terminals 
SEE ALSO 

tn3270(l), map3270(5) 

BUGS 

If the entry for the specific terminal exceeds 1024 bytes, w/i(l) will fail to set the environment variable. 
Mset should probably detect this case and output the path to the map3270 file instead of the terminal 
entry. 
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NAME 

msgs - system messages and junk mail program 
SYNOPSIS 

msgs [ -fhlpq ] [ number ] [ -number ] 
msgs s 

msgs -c [ -days ] 

DESCRIPTION 

Msgs is used to read system messages. These messages are sent by mailing to the login ‘msgs’ and 
should be short pieces of information which are suitable to be read once by most users of the system. 

Msgs is normally invoked each time you login, by placing it in the file .login (.profile if you use 
Ibin/sh). It will then prompt you with the source and subject of each new message. If there is no sub¬ 
ject line, the first few non-blank lines of the message will be displayed. If there is more to the mes¬ 
sage, you will be told how long it is and asked whether you wish to see the rest of the message. The 
possible responses are: 

y type the rest of the message. 

RETURN 

synonym for y. 

n skip this message and go on to the next message. 

- redisplay the last message. 

q drops you out of msgs; the next time you run the program it will pick up where you left off. 

s append the current message to the file “Messages” in the current directory; ‘s-’ will save the 
previously displayed message. A ‘s’ ch* ‘s-’ may be followed by a space and a file name to 
receive the message replacing the default “Messages”. 

m or ‘m-’ causes a copy of the specified message to be placed in a temporary mailbox and 
mail(l) to be invoked on that mailbox. Both ‘m’ and ‘s’ accept a numeric argument in place 
of the ‘-’. 

Msgs keeps track of the next message you will see by a number in the file .msgsrc in your home direc¬ 
tory. In the directory lusr/msgs it keeps a set of files whose names are the (sequential) numbers of the 
messages they represent The file fusr/msgsfbounds shows the low and high number of the messages in 
the directory so that msgs can quickly determine if there are no messages for you. If the contents of 
bounds is incorrect it can be fixed by removing it; msgs will make a new bounds file the next time it is 
run. 

The -s option is used for setting up the posting of messages. The line 
msgs: "I /usr/ucb/msgs -s" 

should be include in fusriliblaliases to enable posting of messages. 

The -c option is used for performing cleanup on /usrimsgs. An entry with the -c option should be 
placed in lusrilibicrontab to run every night. This will remove all messages over 21 days old. A 
different expiration may be specified on the command line to override the default. 

Options when reading messages include: 

-f which causes it not to say “No new messages.”. This is useful in your .login file since this is 
often the case here. 

-q Queries whether there are messages, printing “There are new messages.” if there are. The 
command “msgs -q” is often used in login scripts. 

-h causes msgs to print the first part of messages only. 
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-1 option causes only locally originated messages to be reported. 

num A message number can be given on the command line, causing msgs to start at the specified 
message rather than at the next message indicated by your .msgsrc file. Thus 

msgs -h 1 

prints the first part of all messages. 

-number 

will cause msgs to start number messages back from the one indicated by your .msgsrc file, 
useful for reviews of recent messages. 

-p causes long messages to be piped through more(l). 

Within msgs you can also go to any specific message by typing its number when msgs requests input as 
to what to do. 

FILES 

/usr/msgs/* database 

“/.msgsrc number of next message to be presented 

AUTHORS 

William Joy 
David Wasley 

SEE ALSO 

aliases(5), crontab(5), mail(l), more(l) 

BUGS 
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NAME 

mt - magnetic tape manipulating program 
SYNOPSIS 

mt [ -f tapename ] command [ count ] 

DESCRIPTION 

Mt is used to give commands to a magnetic tape drive. If a tape name is not specified, the environment 
variable TAPE is used; if TAPE does not exist, mt uses the device Idevlrmtll. Note that tapename 
must reference a raw (not block) tape device. By default mt performs the requested operation once. 
Operations may be performed multiple times by specifying count. 

The available commands are listed below. Only as many characters as are required to uniquely identify 
a command need be specified. 

eof, weof 

Write count end-of-file marks at the current position on the tape, 
fsf Forward space count files, 

fsr Forward space count records, 

bsf Back space count files, 

bsr Back space count records, 

rewind Rewind the tape (Count is ignored), 
oraine, rewoffl 

Rewind the tape and place the tape unit off-line (Count is ignored), 
status Print status information about the tape unit. 

Mt returns a 0 exit status when the operation(s) were successful, 1 if the command was unrecognized, 
and 2 if an operation failed. 

FILES 

/dev/rmt* Raw magnetic tape interface 
SEE ALSO 

mtio(4), dd(l), ioctl(2), environ(7) 
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NAME 

mv - move or rename files 
SYNOPSIS 

mv [-i] [-f ] [-] filel file2 
mv [ -i ] [ -f ] [ - ] file ... directory 
DESCRIPTION 

Afv moves (changes the name of) filel to filel. 

If filel already exists, it is removed before filel is moved. If filel has a mode which forbids writing, 
mv prints the mode (see chmod(2)) and reads the standard input to obtain a line; if the line begins with 
y, the move takes place; if not, mv exits. 

In the second form, one or more files (plain files or directories) are moved to the directory with their 
original file-names. 

Mv refuses to move a file onto itself. 

Options: 

-i stands for interactive mode. Whenever a move is to supercede an existing file, the user is 
prompted by the name of the file followed by a question mark. If he answers with a line start¬ 
ing with ’y’, the move continues. Any other reply prevents the move from occurring. 

-f stands for force. This option overrides any mode restrictions or the -i switch. 

means interpret all the following arguments to mv as file names. This allows file names start¬ 
ing with minus. 

EUNICE NOTES 

This utility requires that there is only one version of the file to be moved. EUNICE, 1 VERSION must 
be ON. See letcleuniceleumce.com. 

SEE ALSO 

cp(l). ln(I) 

BUGS 

If filel and filel lie on different file systems, mv must copy the file and delete the original. In this case 
the owner name becomes that of the copying pnx:ess and any linking relationship with other files is 
lost 
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NOTE 


WOLLONGONG’S WIN/TCP PRODUCT 


NAME 

netstat - show network status 
SYNOPSIS 

netstat [ -Aan ] [ -f addressjamily ] [ system ] [ core ] 
netstat [ -himnrs ] [ -f address_family ] [ system ] [ core ] 
netstat [ -n ] [ -I interface ] interval [ system ] [ core ] 

DESCRIPTION 

The netstat command symbolically displays the contents of various network-related d ^ ta structures. 
There are a number of output formats, depending on the options for the information presented. The 
first form of the command displays a list of active sockets for each protocol. The second form presents 
the contents of one of the other network data structures according to the option selected. Using the 
third form, with an interval specified, netstat will continuously display the information regarding packet 
traffic on the configured network interfaces. 

The options have the following meaning: 

-A With the default display, show the address of any protocol control blocks associated with sock¬ 
ets; used for debugging. 

-a With the default display, show the state of all sockets; normally sockets used by server 
processes are not shown. 

-h Show the state of the IMP host table. 

-i Show the state of interfaces which have been auto-configured (interfaces statically configured 
into a system, but not located at boot time are not shown). 

-I interface 

Show information only about this interface; used with an interval as described below. 

-m Show statistics recorded by the memory management routines (the network manages a private 
pool of memory buffers). 

-n Show network addresses as numbers (normally netstat interprets addresses and attempts to 
display them symbolically). This option may be used with any of the display formats. 

-s Show per-protocol statistics. 

-r Show the routing tables. When -s is also present, show routing statistics instead. 

-f addressjamily 

Limit statistics or address control block reports to those of the specified address family. The 
following address families are recognized: inet, for AF_INET, ns, for AF_NS, and mix, for 
AF_UNIX. 

The arguments, system and core allow substitutes for the defaults “/vmunix” and “/dev/kmem”. 

The default display, for active sockets, shows the local and remote addresses, send and receive queue 
sizes (in bytes), protocol, and the internal state of the protocol. Address formats are of the form 
“hosLport” or “netwoik.port” if a socket’s address specifies a network but no specific host address. 
When known the host and network addresses are displayed symbolically according to the data bases 
/etcfhosts and !etc!networks, respectively. If a symbolic name for an address is unknown, or if the -n 
option is specified, the address is printed numerically, according to the address family. For more infor¬ 
mation regarding the Internet “dot format,’’ refer to /net(3N). Unspecified, or “wildcard”, addresses 
and ports appear as 
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The interface display provides a table of cumulative statistics regarding packets transferred, errors, and 
collisions. The network addresses of the interface and the maximum transmission unit (“mtu”) are also 
displayed. 

The routing table display indicates the available routes and their status. Each route consists of a desti¬ 
nation host or network and a gateway to use in forwarding packets. The flags field shows the state of 
the route (“U” if “up”), whether the route is to a gateway (“G”), and whether the route was created 
dynamically by a redirect (“D”). Direct routes are created for each interface attached to the local host; 
the gateway field for such entries shows the address of the outgoing interface. The refcnt field gives 
the current number of active uses of the route. Connection oriented protocols normally hold on to a 
single route for the duration of a connection while connectionless protocols obtain a route while sending 
to the same destination. The use field provides a count of the number of packets sent using that route. 
The interface entry indicates the network interface utilized for the route. 

When netstat is invoked with an interval argument, it displays a running count of statistics related to 
network interfaces. This display consists of a column for the primary interface (the first interface found 
during autoconfiguration) and a column summarizing information for all interfaces. The primary inter¬ 
face may be replaced with another interface with the -7 option. The first line of each screen of infor¬ 
mation contains a summary since the system was last rebooted. Subsequent lines of output show values 
accumulated over the preceding interval. 

EUNICE NOTES 

This file is pertinent only to customers who have Wollongong’s WIN/TCP product 
SEE ALSO 

iostat(l), vmstat(l), hosts(5), networks(5), protocols(5), services(5) 

BUGS 

The notion of errors is ill-defined. Collisions mean something else for the IMP. 
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NAME 

newaliases - rebuild the data base for the mail aliases file 

SYNOPSIS 

newaliases 

DESCRIPTION 

Newaliases rebuilds the random access data base for the mail aliases file lusrfliblaliases. It must be run 
each time lusr/libfaliases is changed in order for the change to take effect. 

SEE ALSO 

aliases(5), sendmail(8) 
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NAME 

nice, nohup - run a command at low priority (sh only) 

SYNOPSIS 

nice [ -number ] command [ arguments ] 
nohup command [ arguments ] 

DESCRIPTION 

Nice executes command with low scheduling priority. If the number argument is present, the priority is 
incremented (higher numbers mean lower priorities) by that amount up to a limit of 20. The default 
number is 10. 

The super-user may run commands with priority higher than normal by using a negative priority, e.g. 
‘— 10 ’. 

Nohup executes command immune to hangup and terminate signals from the controlling terminal. The 
priority is incremented by 5. Nohup should be invoked from the shell with *&’ in order to prevent it 
from responding to interrupts by or stealing the input from the next person who logs in on the same ter¬ 
minal. 

FILES 

nohup.out standard output and standard error file under nohup 
SEE ALSO 

csh(l), setpriority(2), renice(8) 

DIAGNOSTICS 

Nice returns the exit status of the subject command. 

BUGS 

Nice and nohup are particular to 5/i(l). If you use csh{\), then commands executed with are 
automatically immune to hangup signals while in the background. There is a builtin command nohup 
which provides immunity from terminate, but it does not redirect ouQ}ut to nohup.out. 

Nice is built into C5A(1) with a slightly different syntax than described here. The form “nice +10“ 
nices to positive nice, and “nice -10” can be used by the super-user to give a process more of the pro¬ 
cessor. 
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NAME 

nm - print name list 
SYNOPSIS 

nm [ -agnopni ] [ file ... ] 

DESCRIPTION 

Nm prints the name list (symbol table) of each object file in the argument list. If an argument is an 
archive, a listing for each object file in the archive will be produced. If no file is given, the symbols in 
"a.out" are listed. 

Each symbol name is preceded by its value (blanks if undefined) and one of the letters U (undefined), A 
(absolute), T (text segment symbol), D (data segment symbol), B (bss segment symbol), C (common 
symbol), f file name, or - for debugger symbol table entries (see -a below). If the symbol is local 
(non-external) the type letter is in lower case. The output is sorted alphabetically. 

Options are: 

—a Print symbol table entries inserted for use by debuggers. 

-g Print only global (external) symbols. 

-n Sort numerically rather than alphabetically. 

-o Prepend file or archive element name to each output line rather than only once. 

-p Don’t sort; print in symbol-table order. 

-r Sort in reverse order. 

-u Print only undefined symbols. 

SEE ALSO 

ar(l), ar(5), a.out(5), stab(5) 
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NAME 

nroff - text formatting 
SYNOPSIS 

nroff [ option ] ... [ file ]... 

DESCRIPTION 

formats text in the named files for typewriter-like devices. See also troff(l). The full capabilities 
of nroff ax& described in the NroffTTroff User's Manual. 

If no file argument is present, the standard input is read. An argument consisting of a single minus (-) 
is taken to be a file name corresponding to the standard input 

The options, which may appear in any order so long as they appear before the files, are: 

-olist Print only pages whose page numbers appear in the comma-separated list of numbers and 
ranges. A range N-M means pages N through M\ an initial -N means from the beginning to 
page N\ and a final N- means from N to the end. 

-hN Number first generated page N. 

sN Stop every N pages. Nroff v/iU halt prior to every N pages (default N-l) to allow paper load¬ 
ing or changing, and will resume upon receipt of a newline. 

--mname Prepend the macro file /usr/lib/tmac/tmac.name to the input files. 

-roN Set register a (one-character) to N. 

-i Read standard input after the input files are exhausted. 

-q Invoke the simultaneous input-output mode of the rd request. 

-Tname Prepare output for specified terminal. Known names are 37 for the (default) Teletype Cor- 
poratitm Model 37 terminal, tii300 for the GE TermiNet 300 (or any terminal without half-line 
capability), 300S for the DASI-300S, 300 for the DASI-300, and 450 for the DASI450 (Diablo 
Hyterm). 

-e Produce equally-spaced words in adjusted lines, using full terminal resolution. 

~h Use output tabs during horizontal spacing to speed output and reduce output character count. 
Tab settings are assumed to be every 8 nominal character widths. 

FILES 

/tmp/ta* tempOTary file 

/usr/lib/tmac/tmac.* standard macro files 
/usrAib/term/* terminal driving tables for nroff 

SEE ALSO 

J. F. Ossanna, Nroff/Troff user’s manual 

B. W. Kemighan, A TROFF Tutorial 

troff(l), eqn(l), tbl(l), ms(7), me(7), man(7), col(l), lpr(l) 

BUGS 

nroffil) causes a single word to be printed when a paragraph breaks across pages. 
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NAME 

od - octal, decimal, hex, ascii dump 
SYNOPSIS 

od [ -format ] [ file ] [ [+]offset[.3[b] [label] ] 

DESCRIPTION 

Od displays yi/e, or it’s standard input, in one or more dump formats as selected by the first argument. 
If the first argument is missing, -o is the default. Dumping continues until end-of-file. 

The meanings of the format argument charactei^ are: 

a Interpret bytes as characters and display them with their ACSn names. If the p character is given 
also, then bytes with even parity are und»lined. The P character causes bytes with odd parity to 
be underlined. Otherwise the parity bit is ignored. 

b Interpret bytes as unsigned octal. 

c Interpret bytes as ASCII characters. Certain non-graphic characters appear as C escapes: null=\0, 
backspace=Nb, formfeed=\f, newline=\n, retum=\r, tab=\t; others appear as 3-digit octal numbers. 
Bytes with the parity bit set are displayed in octal. 

d Interpret (short) words as unsigned decimal, 
f Interpret long words as floating point, 
h Interpret (short) words as unsigned hexadecimal, 
i Interpret (short) words as signed decimal. 

1 Interpret long words as signed decimal, 
o Interpret (short) words as unsigned octal. 

s[n] Look for strings of ascii graphic characters, terminated with a null byte. N specifies the minimum 
length string to be recognized. By default, the minimum length is 3 characters. 

V Show all data. By default, display lines that are identical to the last line shown are not output, but 
are indicated with an in column 1. 

w[n] Specifies the number of input bytes to be interpreted and displayed on each output line. If w is 
not specified, 16 bytes are read for each display line. If n is not specified, it defaults to 32. 

X Interpret (short) words as hexadecimal. 

An upper case format character implies the long or double precision form of the object. 

The offset argument specifies the byte offset into the file where dumping is to commence. By default 
this argument is interpreted in octal. A different radix can be specified; If is appended to the argu¬ 
ment, then offset is interpreted in decimal. If offset begins with “x” or “Ox”, it is interpreted in hexa¬ 
decimal. If “b” (“B”) is appended, the offset is interpreted as a block count, where a block is 512 
(1024) bytes. If the file argument is omitted, an offset argument must be preceded by “+”. 

The radix of the displayed address will be the same as the radix of the offset, if specified; otherwise it 
will be octal. 

Label will be interpreted as a pseudo-address for the first byte displayed. It will be shown in “0” fol¬ 
lowing the file offset. It is intended to be used with core images to indicate the real memory address. 
The syntax for label is identical to that for offset. 

SEE ALSO 

adb(l) 

BUGS 

A file name argument can’t start with “+”. A hexadecimal offset can’t be a block count. Only one 
file name argument can be given. 
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It is an historical botch to require specification of object, radix, and sign representation in a single char¬ 
acter argument 
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NAME 

pagesize - print system page size 

SYNOPSIS 

pagesize 

DESCRIPTION 

Pagesize prints the size of a page of memory in bytes, as returned by getpagesize{2). This program is 
useful in constructing portable shell scripts. 

SEE ALSO 

getpagesize(2) 
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NAME 

chfn, chsh, passwd - change password file information 
SYNOPSIS 

passwd [ -f ] [ -s ] [ name ] 

DESCRIPTION 

This command changes (ot installs) a password, login shell (-s option), or GECOS information field (-f 
option) associated with the user name (your own name by default). 

When altering a password, the program prompts for the current password and then for the new one. 
The caller must supply both. The new password must be typed twice to forestall mistakes. 

New passwords must be at least four characters long if they use a sufficiently rich alphabet and at least 
six characters long if monocase. These rules are relaxed if you are insistent enough. 

Only the owner of the name or the super-user may change a password; the owner must prove he knows 
the old password. 

When altering a login shell, passwd displays the current login shell and then prompts for the new one. 
The new login shell must be one of the approved shells listed in /etcishells unless you are the super- 
user. If fetc/shells does not exist, the only shells that may be specified are Ibin/sh and fbintcsh. 

The super-user may change anyone’s login shell; normal users may only change their own login shell. 

When altering the GECOS information field, passwd displays the current information, broken into fields, 
as interpreted by the jingeriX) program, among others, and prompts for new values. These fields 
include a user’s “real life’’ name, office room number, office phone number, and home phone number. 
Included in each prompt is a default value, which is enclosed between brackets. The default value is 
accepted simply by typing a carriage return. To enter a blank field, the word “none” may be typed. 
Below is a sample run: 

Name [Biff Studsworth H]: 

Room number (Exs: 597E or 197C) []: 521E 

Office Phone (Ex: 1632) []: 1863 

Home Phone (Ex: 987532) [5771546]: none 

Passwd allows phone numbers to be entered with or without hyphens. It is a good idea to run finger 
after changing the GECOS information to make sure everything is setup properly. 

The super-user may change anyone’s GECOS information; normal users may only change their own. 
EUNICE NOTES 

All password authentication is done by VMS and not EUNICE. Running the command will not change 
the letcipassword file, but will change the VMS password instead. 

The commands chfn and chsh are not implemented in EUNICE. 

FILES 

/etc/passwd The file containing all of this information 
/etc/shells The list of approved shells 

SEE ALSO 

login(l), finger(l), passwd(5), crypt(3) 

Robert Morris and Ken Thompson, UNIX password security 
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NAME 

pc - Pascal compiler 
SYNOPSIS 

pc [ option ] [ -i name ... ] name ... 

DESCRIPTION 

Pc is a Pascal compiler. If given an argument file ending with .p, it will compile the file and load it 
into an executable file called, by default, a.out. 

A program may be separated into more than one .p file. Pc will compile a number of argument .p files 
into object files (with the extension .o in place of .p). Object files may then be loaded into an execut¬ 
able a.out file. Exactly one object file must supply a program statement to successfully create an exe¬ 
cutable a.out file. The rest of the files must consist only of declarations which logically nest within the 
program. References to objects shared between separately compiled files are allowed if the objects are 
declared in included header files, whose names must end with .h. Header files may only be included at 
the outermost level, and thus declare only globally available objects. To allow functions and pro¬ 
cedures to be declared, an external directive has been added, whose use is similar to the forward 
directive but restricted to appear only in .h files. Function and procedure bodies may not appear in .h 
files. A binding phase of the compiler checks that declarations are used consistently, to enforce the 
type checking rules of Pascal. 

Object files created by other language processors may be loaded together with object files created by 
pc. The functions and procedures they define must have been declared in .h files included by all the 
.p files which call those routines. Calling conventions are as in C, with var parameters passed by 
address. 

See the Berkeley Pascal User’s Manual for details. 

The following options have the same meaning as in cc(l) and f77(l). See ld(l) for load-time options, 
-c Suppress loading and produce ‘.o’ file(s) from source file(s). 

-g Have the compiler produce additional symbol table information for dbx(l). 

-w Suppress warning messages. 

-p Prepare object files for profiling, see prof(l). 

-O Invoke an object-code improver. 

-S Compile the named program, and leave the assembler-language output on the corresponding file 
suffixed ‘.s’. (No ‘.o’ is created.). 

-o output 

Name the final output file output instead of a.out. 

The following options are peculiar to pc. 

-C Compile code to perform runtime checks, verify assert calls, and initialize all variables to zero 
as in pi. 

-b Block buffer the file output. 

-i Produce a listing for the specified procedures, functions and include files. 

-1 Make a program listing during translation. 

-s Accept standard Pascal only; non-standard constructs cause warning diagnostics. 

-t directory 

Use the given directory for compiler temporary files. 

-z Allow execution profiling with pxp by generating statement counters, and arranging for the crea¬ 
tion of the profile data file pmon.out when the resulting object is executed. 
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Other arguments are taken to be loader option arguments, perhaps libraries of pc compatible routines. 
Certain flags can also be controlled in comments within the program as described in the Berkeley Pas¬ 
cal User’s Manual. 

FILES 

file.p 

/usr^ib/pcO 
/lib/fl 
/usr/lib/pc2 
/Ub/c2 
/usr/lib/pc3 
/usr/lib/pc2.* strings 
^ /usr/libAiow_pc 
/usr/lib/libpc.a 
/usr/lib/libm.a 
/lib/libc.a 

SEE ALSO 

Berkeley Pascal User’s Manual 
pi(l), pxp(l), pxref(l), sdb(l) 

DIAGNOSTICS 

For a basic explanation do 

pc 

See pi(l). for an explanation of the error message format. Internal errors cause messages containing 
the word SNARK. 

AUTHORS 

Charles B. Haley, William N. Joy, and Ken Thompson 

Retargetted to the second pass of the portable C compiler by Peter Kessler 

Runtime library and inline optimizer by M. Kirk McKusick 

Separate compilation consistency checking by Louise Madrid 

BUGS 

The keyword packed is recognized but has no effect. 

The binder is not as strict as described here, with regard to the rules about external declarations only in 
‘.h’ files and including ‘.h’ files only at the outermost level. It will be made to perform these checks in 
its next incarnation, so users are warned not to be sloppy. 

The -z flag doesn’t work for separately compiled files. 

Because the -s option is usurped by the compiler, it is not possible to pass the strip option to the 
loader. Thus programs which are to be stripped, must be run through strip (1) after they are compiled. 


pascal source files 
c(»npiler 
code generator 

runtime integrator (inline expander) 
peephole optimizer 

separate compilation consistency checker 
text of the error messages 
basic usage explanation 
intrinsic functions and I/O library 
math library 

standard library, see intro{2>) 
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NAME 

pdx - pascal debugger 

SYNOPSIS 

pdx [-r] [objfile] 

DESCRIPTION 

Pdx is a tool for source level debugging and execution of Pascal programs. The objfile is an object file 
produced by the Pascal translator pi(l). If no objfile is specified, pdx looks for a file named “obj” in 
the current directory. The object file contains a symbol table which includes the name of the all the 
source files translated by pi to create it These files are available for perusal while using the debugger. 

If the file “.pdxinit” exists in the current directory, then the debugger commands in it are executed. 

The -r option causes the objfile to be executed immediately; if it terminates successfully pdx exits. 
Otherwise it reports the reason for termination and offers the user the option of entering the debugger 
or simply letting px continue with a traceback. If -r is not specified, pdx just prompts and waits for a 
command. 

The commands are: 

run [args] [< filename] [> filename] 

Start executing objfile, passing args as command line arguments; < or > can be used to redirect 
input or output in the usual manner. 

trace [in procedurelfunction] [if condition] 
trace source-line-number [if condition] 
trace procedurelfunction [in procedurelfunction] [if condition] 
trace expression at source-line-number [if condition] 
trace variable [in procedurelfunction] [if condition] 

Have tracing information printed when the program is executed. A number is associated with 
the command that is used to turn the tracing off (see the delete command). 

The first argument describes what is to be traced. If it is a source-line-number, then the line is 
printed immediately prior to being executed. Source line numbers in a file other than the 
current one must be preceded by the name of the file and a colon, e.g. “mumble.p:17”. 

If the argument is a procedure or function name then every time it is called, information is 
printed telling what routine called it, from what source line it was called, and what parameters 
were passed to it In addition, its return is noted, and if it’s a function then the value it is 
returning is also printed. 

If the argument is an expression with an at clause then the value of the expression is printed 
whenever the identified source line is reached. 

If the argument is a variable then the name and value of the variable is printed whenever it 
changes. Execution is substantially slower during this form of tracing. 

If no argument is specified then all source lines are printed before they are executed. Execu¬ 
tion is substantially slower during this form of tracing. 

The clause “in procedurelfunction’' restricts tracing information to be printed only while exe¬ 
cuting inside the given procedure or function. 

Condition is a Pascal boolean expression and is evaluated prior to printing the tracing informa¬ 
tion; if it is false then the information is not printed. 
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There is no restriction on the amount of information that can be traced- 
stop if condition 

stop at source-line-number [if condition] 
stop in procedurelfunction [if condition] 
stop variable [if condition] 

Stop execution when the given line is reached, procedure or function called, variable changed, 
or condition true. 

delete command-number 

The trace or stop corresponding to the given number is removed. The numbers associated with 
traces and stops are printed by the status command. 

status [> filename] 

Print out the currently active trace and stop commands. 

cont Continue execution from where it stopped. This can only be done when the program was 
stopped by an interrupt or through use of the stop command. 

step Execute one source line. 

next Execute up to the next source line. The difference between this and step is that if the line 
contains a call to a procedure or function the step command will stop at the beginning of that 
block, while the next command will not 

print expression [, expression ...] 

Print out the values of the Pascal expressions. Variables declared in an outer block but having 
the same identifier as one in the current block may be referenced as ''block-name . variable". 

whatis identifier 

Print the declaration of the given identifier, 
which identifier 

Print the full qualification of the given identifer, i.e. the outer blocks that the identifier is asso¬ 
ciated with. 

assign variable expression 

Assign the value of the expression to the variable. 

call procedure(parameters) 

Execute the object code associated with the named procedure or function, 
help Print out a synopsis of pdx commands. 

gripe Invokes a mail program to send a message to the person in charge of pdx. 

where Print out a list of the active procedures and functions and the respective source line where they 
are called. 

source filename 

Read pdx commands from the given filename. Especially useful when the filename has been 
created by redirecting a status command from an earlier debugging session. 

dump [> filename] 

Print the names and values of all active data. 

list [source-line-number [, source-line-number]] 
list procedurelfunction 

List the lines in the current source file from the first line number to the second inclusive. As 
in the editor “$” can be used to refer to the last line. If no lines are specified, the entire file 
is listed. If the name of a procedure or function is given lines n-k to n-¥k are listed where n is 
the first statement in the procedure or function and k is small. 

file [filename] 
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Change the current source file name to filename. If none is specified then the current source 
file name is printed. 

edit \filename] 

edit procedureffunction-name 

Invoke an editor (mi filename or the current source file if none is specified. If a procedure or 
function name is specified, the editor is invoked on the file that contains it Which editor is 
invoked by default depends on the installation. The default can be overridden by setting the 
environment variable EDITOR to the name of the desired editor. 

pi Recompile the program and read in the new symbol table information, 
sh command-line 

Pass the command line to the shell for execution. The SHELL environment variable deter¬ 
mines which shell is used. 

alias new-command-name old-command-name 

This command makes pdx respond to new-command-name the way it used to respond to old- 
command-name. 

quit Exit pdx. 


The following commands deal with the program at the px instruction level rather than source level. 
They are not intended for general use. 

tracei [address] [if cond] 
tracei [variable] [at address] [if cond] 
stopi [address] [if cond] 
stopi [at] [address] [if cond] 

Turn on tracing or set a stop using a px machine instruction addresses, 
xi address [, address] 

Print the instructions starting at the first address. Instructions up to the second address are 
printed. 

xd address [, address] 

Print in octal the specified data location(s). 

FILES 

obj Pascal object file 

.pdxinit Pdx initialization file 

SEE ALSO 

pi(l), px(l) 

An Introduction to Pdx 

BUGS 

Pdx does not understand sets, and provides no information about files. 

The whatis command doesn’t quite work for variant records. 

Bad things will happen if a procedure invoked with the call command does a non-local goto. 

The commands step and next should be able to take a count that specifies how many lines to execute. 
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There should be commands step! and next! that correspond to step and next but work at the instruction 
level. 

There should be a way to get an address associated with a line number, procedure or function, and vari¬ 
able. 

Most of the command names are too long. 

The alias facility is quite weak. 

A csh-\iik& history capability would improve the situation. 
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NAME 

pi - Pascal interpreter code translator 
SYNOPSIS 

pi [ option ] [ -i name ... ] name.p 
DESCRIPTION 

Pi translates the program in the file name.p leaving interpreter code in the file obj in the current direc¬ 
tory. The interpreter code can be executed using px. Fix performs the functions of pi and px for ‘load 
and go’ Pascal. 

The following flags are interpreted by pi; the associated options can also be controlled in comments 
within the program as described in the Berkeley Pascal User's Manual. 

-b Block buffer the file output. 

-i Enable the listing for any specified procedures and functions and while processing any specified 
include files. 

-1 Make a program listing during translation. 

-n Begin each listed include file on a new page with a banner line. 

-p Suppress the post-mortem control flow backtrace if an error occurs; suppress statement limit 
counting. 

-s Accept standard Pascal only; non-standard constructs cause warning diagnostics. 

-t Suppress runtime tests of subrange variables and treat assert statements as comments. 

-u Card image mode; only the first 72 characters of input lines are used. 

-w Suppress warning diagnostics. 

-z Allow execution profiling with pxp by generating statement counters, and arranging for the crea¬ 
tion of the profile data file pmon.out when the resulting object is executed. 

FILES 

file.p input file 

file.i include file(s) 

/usr/lib/pi2.*strings text of the error messages 

/usr/libA»ow_pi* basic usage explanation 

obj interpreter code ouq7ut 

SEE ALSO 

Berkeley Pascal User’s Manual 
pix(l), px(l), pxp(l), pxref(l) 

DIAGNOSTICS 

For a basic explanation do 

pi 

In the diagnostic output of the translator, lines containing syntax errors are listed with a flag indicating 
the point of error. Diagnostic messages indicate the action which the recovery mechanism took in order 
to be able to continue parsing. Some diagnostics indicate only that the input is ‘malformed.’ This 
occurs if the recovery can find no simple correction to make the input syntactically valid. 

Semantic error diagnostics indicate a line in the source text near the point of error. Some errors evoke 
more than one diagnostic to help pinpoint the error; the follow-up messages begin with an ellipsis 
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The first character of each error message indicates its class: 

E Fatal error; no code will be generated, 

e Non-fatal error, 

w Warning - a potential problem, 

s Non-standard Pascal construct warning. 

If a severe error occurs which inhibits further processing, the translator will give a diagnostic and then 
‘QUIT’. 

AUTHORS 

Charles B. Haley, William N. Joy, and Ken Thompson 
Ported to VAX-11 by Peter Kessler 

BUGS 

The keyword packed is recognized but has no effect. 

For clarity, semantic errors should be flagged at an appropriate place in the source text, and multiple 
instances of the ‘same’ semantic error should be summarized at the end of a procedure or function 
rather than evoking many diagnostics. 

When include files are present, diagnostics relating to the last procedure in one file may appear after 
the beginning of the listing of the next. 
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NAME 

pix - Pascal interpreter and executor 
SYNOPSIS 

pix [ -blnpstuwz ] [ -i name ... ] name.p [ argument... ] 

DESCRIPTION 

Pix is a ‘load and go’ version of Pascal which combines the functions of the interpreter code translator 
pi and the executor px. It uses pi to translate the program in the file namep and, if there were no fatal 
errors during translation, causes the resulting interpreter code to be executed by px with the specified 
arguments. A temporary file is used for the object code; the file obj is neither created nor destroyed. 

FILES 

/usr/ucb/pi Pascal translator 

/usr/ucb/px Pascal execute 

/tmp^ix* temporary 

/usr/lib/how_pix basic explanation 

SEE ALSO 

Berkeley Pascal User’s Manual 
pi(l), px(l) 

DIAGNOSTICS 

For a basic explanation do 

pix 
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NAME 

plot - graphics filters 
SYNOPSIS 

plot [ -Tterminal ] [ -rresolution ] [ files... ] 

DESCRIPTION 

These ctxnmands read plotting instructions plot(5)) from the standard input or the specified files, 

and in graeial produce plotting instructions suitable fra* a particular terminal on the standard output. 
The -r flag may be used to specify the device’s output resolution (currently only the Imagen laser 
printer understands this option). 

If no terminal type is specified, the environment parameter $TERM (see environ(T)) is used. Known 
terminals are: 

4013 Tektronix 4013 storage scope. 

4014 or tek 

Tektronix 4014 or 4015 storage scope with Enhanced Graphics Module. (Use 4013 for Tek¬ 
tronix 4014 or 4015 without the Enhanced Graphics Module). 

450 DASI Hyterm 450 terminal (Diablo mechanism). 

300 DASI 300 or GSI terminal (Diablo mechanism). 

300S DASI 300S terminal (Diablo mechanism), 
aed AED 512 color graphics terminal, 

bitgraph or bg 

BBN bitgraph graphics terminal, 
imagen or ip 

Imagen laser printer (default 240 dots-per-inch resolution), 
crt Any crt terminal capable of running w(l). 

dumb Dumb terminals without cursor addressing or line printers. 
vtl25 DEC vtl25 terminal. 

hp2648 or bp or bp8 

Hewlett Packard 2648 graphics terminal. 

ver Versatec D1200A printer-plotter, 

var Benson Varian printer-plotter. 

These versions of plot use the -g option of lpr(l) to send the result diiecUy to the plotter dev¬ 
ice rather than to the standard output. 

FILES 

/usr/bin/t4013 

/usr/bin/tek 

/usr/bin/t450 

/usr/bin/t300 

/usr/bin/t300s 

/usr/bin/aedplot 

/usr/bin/bgplot 

/usr/bin/crtplot 

/usr/bin/dumbplot 

/usr/bin/gigiplot 

/usr/bin/hpplot 

/usr/bin/implot 
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/usr/ucb/lpr 
SEE ALSO 

plot(3X), plot(3F), plot(5), Ipr(l) 
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NAME 

pmerge - pascal file merger 

SYNOPSIS 

pmerge name.p ... 

DESCRIPTION 

Pmerge assembles the named Pascal files into a single standard Pascal program. The resulting program 
is lis^ on the standard output. It is intended to be used to merge a collection of separately compiled 
modules so that they can be run through pi, or exported to other sites. 

FILES 

/usr/tmp/MG* default temporary files 

SEE ALSO 

pc(l), pi(l), 

Auxiliary documentation Berkeley Pascal User's Manual. 

AUTHOR 

M. Kirk McKusick 

BUGS 

Very minimal error checking is done, so incorrect programs will produce unpredictable results. Block 
comments should be placed after the keyword to which they refer or they are likely to end up in bizarre 
places. 
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NAME 

pr - print file 
SYNOPSIS 

pr [ option ] ... [ file ] ... 

DESCRIPTION 

Pr produces a printed listing of one or more files. The output is separated into pages headed by a date, 
the name of the file or a specified header, and the page number. If there are no file arguments, pr 
prints its standard input. 

Options apply to all following files but may be reset between files: 

-n Produce n-column output. 

+n Begin printing with page n. 

-h Take the next argument as a page header. 

-wn For purposes of multi-column output, take the width of the page to be n characters instead of 
the default 72. 

-f Use formfeeds instead of newlines to separate pages. A formfeed is assumed to use up two 
blank lines at the top of a page. (Thus this option does not affect the effective page length.) 

-In Take the length of the page to be n lines instead of the default 66. 

-t Do not print the 5-line header or the 5-line trailer normally supplied for each page. 

-sc Separate columns by the single character c instead of by the appropriate amount of white 

space. A missing c is taken to be a tab. 

-m Print all files simultaneously, each in one column, 

Inter-terminal messages via write(1) are forbidden during a pr. 

FILES 

/devAty? to suspend messages. 

SEE ALSO 

cat(l), Ipr(l) 

DIAGNOSTICS 

There are no diagnostics when pr is printing on a terminal. 


April 21, 1989 


The Wollongong Group 


1 



PRINTENV(l) 


UNIX Programmer’s Manual 


PRINTENV(l) 


NAME 

printenv - print out the environment 

SYNOPSIS 

printenv [ name ] 

DESCRIPTION 

Printenv prints out the values of the variables in the environment. If a name is specified, only its value 
is printed. 

If a name is specified and it is not defined in the environment, printenv returns exit status 1, else it 
returns status 0. 

SEE ALSO 

sh(l), environ(7), csh(l) 
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NAME 

prof - display profile data 
SYNOPSIS 

prof [ -a ] [ -I ] [ -n ] [ -z ] [ -s ] [ -v [ -low [ -high ] ] ] [ a.out [ mon.out... ] ] 

DESCRIPTION 

Prof int^rets the file produced by the monitor subroutine. Under default modes, the symbol table in 
the named object file (a.out default) is read and correlated with the profile file (monout default). For 
each external symbol, the percentage of time spent executing between that symbol and the next is 
printed (in decreasing orda:), together with the number of times that routine was called and the number 
of milliseconds per call. If more than one profile file is specified, the output represents the sum of the 
profiles. 

In order for the number of calls to a routine to be tallied, the -p option of cc,p7 or pc must have been 

given when the file containing the routine was compiled. This option also arranges for the profile file 

to be produced automatically. 

Options are: 

-a all symbols are reported rather than just external symbols. 

-I the output is sorted by symbol value. 

-n the output is sorted by number of calls 

-s a summary profile file is produced in mon.swn. This is really only useful when more than one 
profile file is specified. 

-V all printing is suppressed and a graphic version of the profile is produced on the standard out¬ 
put for display by the plot(l) filters. When plotting, the numbers low and high, by default 0 
and 100, may be given to cause a selected percentage of the profile to be plotted with accord¬ 
ingly higher resolution. 

-z routines which have zero usage (as indicated by call counts and accumulated time) are 
nevertheless printed in the output. 

FILES 

mon.out for profile 
a.out for namelist 
mon.sum for summary profile 

SEE ALSO 

monitor(3), profil(2), cc(l), plot(lG) 

BUGS 

Beware of quantization errors. 

Is confused byy77 which puts the entry points at the bottom of subroutines and functions. 
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NOTE 


WOLLONGONG’S WIN/TCP PRODUCT 


NAME 

protocols - protocol name data base 
DESCRIPTION 

The protocols file coatains information regarding the known protocols used in the DARPA 
Internet. For each protocol a single line should be present with the following information: 

official protocol name 
protocol number 
aliases 

Items are separated by any number of blanks and/or tab characters. A **# ** indicates the 
beginning of a comment: characters up to the end of the line are not interpreted by routines 
which seardi the file. 

Protocol names may contain any printable character other than a field delimiter, newline, or 
comment character. 

EUNICE NOTES 

This file is pertinent only to customers who have Wollongong’s WIN/TCP product. 

FILES 

/etc/protocols 

SEE ALSO 

getprotoent(3N) 

BUGS 

A name server should be used instead of a static file. 
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NAME 

ps - process status 
SYNOPSIS 

ps [ acegklnstuvwxU# ] 

DESCRIPTION 

Ps prints information about processes. Normally, only your processes are candidates to be printed by 
ps; specifying a causes other users’ processes to be candidates to be printed; specifying x includes 
processes without control terminals in the candidate pool. 

All output formats include, for each process, the process id PID, control terminal of the process TT, cpu 
time used by the process TIME (this includes both user and system time), the state STAT of the pro¬ 
cess, and an indication of the COMMAND which is running. The state is given by a sequence of four 
letters, e.g. “RWNA”. The first letter indicates the runnability of the process: R for runnable 
processes, T for stopped processes, P for processes in page wait, D for those in disk (or other short 
term) waits, S for those sleeping for less than about 20 seconds, and I for idle (sleeping longer than 
about 20 seconds) processes. The second letter indicates whether a process is swapped out, showing W 
if it 4, or a blank if it is loaded (in-core); a process which has specified a soft limit on memory require¬ 
ments and which is exceeding that limit shows >; such a process is (necessarily) not swapped. The 
third letter indicates whether a process is running with altered CPU scheduling priority (nice); if the 
process priority is reduced, an N is shown, if the process priority has been artificially raised then a ‘<’ 
is shown; processes running without special treatment have just a blank. The final letter indicates any 
special treatment of the process for virtual memory replacement; the letters correspond to options to the 
vadvise(2) call; currently the possibilities are A staning for VA_ANOM, S for VA_SEQL and blank 
for VA_NORM; an A typically represents a Usp(l) in garbage collection, S is typical of large image 
processing programs which are using virtual memory to sequentially address voluminous data. 

Here are the options: 

a asks for information about all processes with terminals (ordinarily only one’s own processes are 
displayed). 

c prints the command name, as stored internally in the system for purposes of accounting, rather 
than the command arguments, which are kept in the process’ address space. This is more reli¬ 
able, if less informative, since the process is firee to destroy the latter information. 

e Asks for the environment to be printed as well as the arguments to the command. 

g Asks for all processes. Without this option, ps only prints “interesting” processes. Processes are 

deemed to be uninteresting if they are process group leaders. This normally eliminates top-level 
command interpreters and processes waiting for users to login on free terminals. 

k causes the file /vmcore is used in place of Idevikmem and Idevimem. This is used for postmortem 
system debugging. 

1 asks for a long listing, with fields PPID, CP, PRI, NI, ADDR, SIZE, RSS and WCHAN as 
described below. 

n Asks for numerical output. In a long listing, the WCHAN field is printed numerically rather than 
symbolically, or, in a user listing, the USER field is replaced by a UID field. 

s Adds the size SSIZ of the kernel stack of each process (for use by system maintainers) to the 
basic ouq)ut format. 

tx restricts output to processes whose controlling tty is x (which should be specified as printed by ps, 
e.g. t3 for tty3, tco for console, tdO for ttydO, t? for processes with no tty, t for processes at the 
current tty, etc). This option must be the last one given. 

u A user oriented output is produced. This includes fields USER, %CPU, NICE, SIZE, and RSS as 
described below. 
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V A version of the output containing virtual memory statistics is ou^ut. This includes fields RE, 
SL, PAGEIN, SIZE, RSS, LIM, TSIZ, TRS, %CPU and %MEM, described below. 

w Use a wide output format (132 columns rather than 80); if repeated, e.g. ww, use arbitrarily wide 
ouq}ut. This information is used to decide how much of long commands to print. 

X asks even about processes with no terminal. 

U causes ps to update a private database wh^e is keeps system information. Thus “ps U” should 
be included in the /etc^ file. 

# A process number may be given, (indicated here by #), in which case the output is restricted to 
that process. This option must also be last 

A second argument is taken to be the file containing the system’s namelist. Otherwise, /vmunix is used. 
A third argument tells ps where to look for core if the k option is given, instead of /vmcore. If a fourth 
argument is given, it is taken to be the name of a swap file to use instead of the default /dev/drum. 

Fields which are not common to all output formats: 

USER name of the owner of the process 

%CPU cpu utilizaticMi of the process; this is a decaying average over up to a minute of previous 
(real) time. Since the time base over which this is computed varies (since processes may 
be very young) it is possible for the sum of all %CPU fields to exceed 100%. 

NICE (or NI) process scheduling increment (see setpriority(2)) 

SIZE virtual size of the process (in 1024 byte units) 

RSS real memory (resident set) size of the process (in 1024 byte units) 

LIM soft limit on memory used, specified via a call to setrlimit(2); if no limit has been specified 

then shown as xx 

TSIZ size of text (shared program) image 
TRS size of resident (real memory) set of text 
%MEM percentage of real memory used by this process. 

RE residency time of the process (seconds in core) 

SL sleep time of the process (seconds blocked) 

PAGEIN number of disk i/o’s resulting from references by the process to pages not loaded in core. 
UID numerical user-id of process owner 
PPID numerical id of parent of process 
CP short-term cpu utilization factor (used in scheduling) 

PRI process priority (non-positive when in non-interruptible wait) 

ADDR sw£^ address of the process 

WCHAN event on which process is waiting (an address in the system). A symbol is chosen that 
classifies the address, unless numerical ouq)ut is requested (see the n flag). In this case, the 
initial part of the address is trimmed off and is printed hexadecimally, e.g., 0x80004000 
prints as 4000. 

F flags associated with process as in <syslproc.h>: 


SLOAD 

000001 

in core 

SSYS 

000002 

swapper or pager process 

SLOCK 

000004 

process being swapped out 

SSWAP 

000008 

save area flag 

STRC 

000010 

process is being traced 

SWTED 

000020 

another tracing flag 

SULOCK 

000040 

user settable lock in core 

SPACE 

000080 

process in page wait state 

SKEEP 

000100 

another flag to prevent swap out 

SDLYU 

000200 

delayed unlock of pages 

SWEXIT 

000400 

working on exiting 
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SPHYSIO 

000800 

SVFORK 

001000 

SVFDONE 

002000 

SNOVM 

004000 

SPAGI 

008000 

SANOM 

010000 

SUANOM 

020000 

STIMO 

040000 

SDETACH 

080000 

SOUSIG 

100000 


doing physical i/o (bio.c) 

process resulted from vforkO 

another vfork flag 

no vm, parent in a vforkQ 

init data space on demand from inode 

system detected anomalous vm behavior 

user warned of anomalous vm behavior 

timing out during sleep 

detached inherited by init 

using old signal mechanism 


A process that has exited and has a parent that has not yet waited for the process is marked <defunct>; 
a process which is blocked trying to exit is marked <exiting>; Ps makes an educated guess as to the file 
name and arguments given when the process was created by examining memory or the swap area. The 
method is inherently somewhat unreliable and in any event a process is entitled to destroy this informa¬ 
tion, so the names cannot be counted on too much. 


FILES 


/vmunix system namelist 

/dev/kmem kernel memory 

/dev/drum swap device 

/vmcore core file 

/dev searched to find swap device and tty names 

/etc/psdatabase system namelist, device, and wait channel information 


SEE ALSO 

kill(l). w(l) 


BUGS 

Things can change while ps is running; the picture it gives is only a close approximation to reality. 
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NAME 

ptx - permuted index 
SYNOPSIS 

ptx [ option ] ... [ input [ output ] ] 

DESCRIPTION 

Ptx generates a permuted index to file input (mi file output (standard input and output default). It has 
three phases: the first does the permutation, gen^ting wie line for each keyword in an input line. The 
keyword is rotated to the front. The permuted file is then sorted. Finally, the sorted lines are rotated so 
the keyword comes at the middle of the page. Ptx produces output in the form: 

.XX "tail" "before keyword" "keyword and after" "head" 

where .xx may be an nroff or trpff(l) macro for user-defined formatting. The b^ore keyword and key¬ 
word and after fields incorporate as much of the line as will fit around the keyword when it is printed 
at the middle of the page. Tail and head, at least one of which is an empty string "", are wrapped¬ 
around pieces small enough to fit in the unused space at the opposite end of the line. When original 
text must be discarded, 7’ marks the spot. 

The following options can be applied: 

-f Fold upper and lower case letters for sorting. 

-t Prepare the ou^ut for the phototypesetter; the default line length is 100 characters. 

-w n Use the next argument, n, as the width of the output line. The default line length is 72 charac¬ 

ters. 

-g n Use the next argument, n, as the number of characters to allow for each gap among the four 
parts of the line as finally printed. The default gap is 3 characters. 

-o only Use as keywords only the words given in the only file. 

-i ignore 

Do not use as keywords any words given in the ignore file. If the -i and -o options are miss¬ 
ing, use /usrilib/eign as the ignore file. 

-b break 

Use the characters in the break file to separate words. In any case, tab, newline, and space 
characters are always used as break characters. 

-r Take any leading nonblank characters of each input line to be a reference identifier (as to a 
page or chapter) separate from the text of the line. Attach that identifier as a 5th field on each 
ouQ}ut line. 

The index for this manual was generated using ptx, 

FILES 

/usr/bin/sort 

/usrAib/eign 

BUGS 

Line length counts do not account for overstriking or proportional spacing. 
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NAME 

pwd - working directory name 

SYNOPSIS 

pwd 

DESCRIPTION 

Pwd prints the pathname of the working (current) directory. 

SEE ALSO 

cd(l), csh(l), getwd(3) 

BUGS 

In csh(l) the command dirs is always faster (although it can give a different answer in the rare case 
that the current directory or a containing directory was moved after the shell descended into it). 
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NAME 

px - Pascal interpreter 
SYNOPSIS 

px [ obj [ argument... ] ] 

DESCRIPTION 

Px interprets the abstract machine code generated by pi. The first argument is the file to be interpreted, 
and defaults to obj ; remaining arguments are available to the Pascal program using the built-ins argv 
and argc. Px is also invoked by pix when running ‘load and go’. 

If the program terminates abnormally an error message and a control flow backtrace are printed. The 
number of statements executed and total execution time are printed after normal termination. The p 
option of pi suppresses all of this except the message indicating the cause of abnormal termination. 

FILES 

obj default object file 

pmon.out profile data file 

SEE ALSO 

Berkeley Pascal User’s Manual 
pi(l), pix(l) 

DIAGNOSTICS 

Most run-time error messages are self-explanatory. Some of the more unusual ones are: 

Reference to an inactive file 

A file other than input or output was used before a call to reset ot rewrite. 

Statement count limit exceeded 

The limit of 500,000 executed statements (which prevents excessive looping or recursion) has 
been exceeded. 

Bad data found on integer read 
Bad data found on real read 

Usually, non-numeric input was found for a number. For reals, Pascal requires digits before and 
after the decimal point so that numbers like ‘.1’ or ‘21.’ evoke the second diagnostic. 

panic: Some message 

Indicates an internal inconsistency det^ted in px probably due to a Pascal system bug. 

AUTHORS 

Charles B. Haley, William Joy, and Ken Thompson 
VAX-11 version by Kirk McKusick 

BUGS 

Post-mortem traceback is not limited; infinite recursion leads to almost infinite traceback. 
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NAME 

pxp - Pascal execution profiler 
SYNOPSIS 

pxp [ -acdefjnstuw_ ] [ -23456789 ] [ -z [ name ... ] ] name.p 
DESCRIPTION 

Pxp can be used to obtain execution profiles of Pascal programs or as a pretty-printer. To produce an 
execution profile all that is necessary is to translate the program specifying the z option to pi or pix, to 
execute the program, and to then issue the command 

pxp -z name.p 

A reformatted listing is output if none of the c, t, or z options are specified; thus 
pxp old.p > new.p 

places a pretty-printed version of the program in *old.p’ in the file ‘new.p’. 

The use of the following options of pxp is discussed in sections 2.6, 5.4, 5.5 and 5.10 of the Berkeley 
Pascal User's Manual. 

-a Print the bodies of all procedures and functions in the profile; even those which were never exe¬ 
cuted. 

-c Extract profile data from the file core. 

-d Include declaration parts in a profile. 

-e Eliminate include directives when reformatting a file; the include is replaced by the reformatted 
contents of the specified file. 

-f Fully parenthesize expressions. 

-j Left justify all procedures and functions. 

-n Eject a new page as each file is included; in profiles, print a blank line at the top of the page. 

-s Strip comments from the input text 

-t Print a table summarizing procedure and function call counts. 

-u Card image mode; only the first 72 characters of input lines are used. 

-w Suppress warning diagnostics. 

-z Generate an execution profile. If no name s, are given the profile is of the entire program. If a 
list of names is given, then only any specified procedures or functions and the contents of any 
specified include files will appear in the profile. 

Underline keywords. 

-d With d a digit, 2< d<9, causes pxp to use d spaces as the basic indenting unit. The default is 
4. 

FILES 

name.p input file 

name.i include file(s) 

pmon.out profile data 

core profile data source with -c 

/usr/lib/how_pxp information on basic usage 
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SEE ALSO 

Berkeley Pascal User’s Manual 
pi(l), px(l) 

DIAGNOSTICS 

For a basic explanation do 

pxp 

Error diagnostics include ‘No profile data in file’ with the c option if the z option was not enabled to 
pi; ‘Not a Pascal system core file’ if the core is not firom a px execution; ‘Program and count data do 
not COTrespond’ if the program was changed aftCT compilation, before profiling; or if the wrong program 
is specified. 

AUTHOR 

William Joy 

BUGS 

Does not place multiple statements per line. 
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NAME 

pxref - Pascal cross-reference program 

SYNOPSIS 

pxref [ - ] name 

DESCRIPTION 

Pxref makes a line numbered listing and a cross-reference of identifier usage for the program in name. 
The optional argument suppresses the listing. The keywords goto and label are treated as identifiers 
for the purpose of tiie cross-reference. Include directives are not processed, but cause the placement of 
an entry indexed by ‘#include’ in the cross-reference. 

SEE ALSO 

Berkeley Pascal User’s Manual 

AUTHOR 

Niklaus Wirth 

BUGS 

Identifiers are trimmed to 10 characters. 
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NOTE 


NOT PRESENT IN WOLLONGONG’S EUNICE! 


NAME 

quota - display disk usage and limits 
SYNOPSIS 

quota [ -qv ] [ user ] 

DESCRIPTION 

Quota displays users disc usage and limits. Only the super-user may use the optional user argument to 
view the limits of users other than himself. 

The —q flag prints a more terse message, containing only information on file systems where usage is 
over quota. 

If a -V flag is supplied, quota will also display user’s quotas on file systems where no storage is allo¬ 
cated. 

Quota reports only on file systems which have disc quotas. If quota exits with a non-zero status, one or 
more file systems are over quota. 

EUNICE NOTES 

Not implemented in EUNICE. 

SEE ALSO 

quota(2) 
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NAME 

ranlib - convert archives to random libraries 
SYNOPSIS 

ranlib [ -t ] archive ... 

DESCRIPTION 

Ranlib converts each archive to a form which the loader can load more rapidly. Ranlib does this by 

adding a table of contents called_.SYMDEF to the beginning of the archive. Ranlib uses ar(l) to 

reconstruct the archive, so that sufficient temporary file space must be available in the file system which 
contains the current directory. 

If given the -t option, ranlib only "touches" the archives and does not modify them. This is useful 
after copying an archive or using the -t option of make(l) in order to avoid having W(l) complain 
about an “out of date” symbol table. 

SEE ALSO 

ld(l), ar(l), lorder(l), make(l) 

BUGS 

Because generation of a library by ar and randomization of the library by ranlib are separate processes, 
phase errors are possible. The loader, W, warns when the modification date of a library is more recent 
than the creation date of its dictionary; but this means that you get the warning even if you only copy 
the library. 
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NAME 

ratfor - rational Fortran dialect 
SYNOPSIS 

ratfor [ q)tion ... ] [ filename ... ] 

DESCRIPTION 

Ratfor converts a rational dialect of Fortran into ordinary irrational Fortran. Ratfor provides control 
flow constructs essentially identical to those in C: V 

statement grouping; 

{ statement; statement; statement } 

decision-making: 

if (condition) statement [ else statement ] 
switch (integer value) { 

case integer: statement 

[ default: ] statement 

} 

loops: while (condition) statement 

for (expression; condition; expression) statement 

do limits statement 

repeat statement [ until (condition) ] 

break 

next 

and some syntactic sugar to make programs easier to read and write: 
free form input: 

multiple statements/line; automatic continuation 

comments: 

# this is a comment 

translation of relationals: 

>, >*, etc., become .GT., .GE., etc. 

return (expression) 

returns expression to caller from fimction 
define: define name replacement 
include: include filename 
Ratfor is best used with f77(l). 

SEE ALSO 

f77(l) 

B. W. Kemighan and P. J. Plauger, Software Tools^ Addison-Wesley, 1976. 
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NOTE 


WOLLONGONG’S WIN/TCP PRODUCT 


NAME 

Tcp - renote file cq)y 

SYNOPSIS 

rep [ -p ] filel file2 

rep [ -p ][ -HT ] file ... directory 

DESCRIPTION 

Rep copies files between machines. Each file or directory argument is either a remote file name of the 
form “rhostpath”, or a local file name (containing no characters, or a 7’ before any ‘:’s). 

If the <Hr optiem is specified and any of the source files are directories, rep copies each subtree rooted at 
that name; in this case die destination must be a directory. 

By default, the mode and own» of filel are {reserved if it already existed; otherwise the mode of the 
source file modified by the wnask(2) on the destination host is used. The ^ option causes rep to 
attempt to {seserve (duplicate) in its copies the modification times and modes of the source files, ignor¬ 
ing the umask. 

If path is not a full path name, it is interpreted relative to your login directory on rhost. A path on a 
remote host may be quoted (using \ ", or 0 so that the metacharacters are intopreted remotely. 

Rep does not prompt for passwords; your current local user name must exist on rhost and allow remote 
command execution via rs/t(lC). 

Rep handles third party copies, where neither source nor target files are on the current machine. Host- 
names may also thke the form **mame@ihost” to use rname rather than the current user name on the 
remote host The destination hostname may also take the form “rhostmame” to support destination 
machines that are running 4.2BSD versions of rep. 

EUNICE NOTES 

This file is pertinent only to customers who have Wollongong’s WIN/TCP product 
SEE ALSO 

cp(l), ftp(lC), rsh(lC), rlogin(lC) 

BUGS 

Doesn’t detect all cases where the target of a copy might be a file in cases where only a directory 
should be legal. 

Is confused by any output generated by commands in a .login, .profile, or .eshre file on the remote host. 
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NAME 

res - change RCS file attributes 

SYNOPSIS 

res [ options ] file ... 

DESCRIPTION 

Res creates new RCS files or changes attributes of existing (Hies. An RCS file contains multiple revi¬ 
sions of text, an access list, a change log, descriptive text, and some control attributes. For res to work, 
the callo^’s login name must be on the access list, excqpt if the access list is empty, the caller is the 
owno- of the file or the superuser, or the •! option is present 

Files ending in ‘,v’ arc RCS files, all oth^ are woridng files. If a woricing file is given, res tries to find 
the corresponding RCS file first in directory 7RCS and then in the current directory, as explained in eo 
( 1 ). 

-4 creates and initializes a new RCS file, but does not deposit any revision. If the RCS file 

has no path prefix, res tries to place it first into the subdirectory TRCS, and then into the 
current directory. If the RCS file already exists, an error message is printed. 

-aloguts appends the login names appearing in the comma-separated list logins to the access list of 
the RCS file. 

-Xoldfile appends the access list of oldfile to the access list of the RCS file. 


■^[logins] 


-cstring 


-l[rev] 


-u[rev] 


-L 
-U 

-«name[:rev] 


erases the login names appearing in the cennma-separated list logins firom the access list of 
the RCS file. If logins is omitted, the entire access list is erased. 

sets the commoit leado* to string. The comment leader is printed before every log mes¬ 
sage line generated by the keyword $Log$ during checkout (see eo). This is useful for 
programming languages without multi-line comments. During res -i or initial d, the com¬ 
ment leader is guessed from the suffix of the working file. 

locks the revision with number rev. If a branch is given, the latest revision on that branch 
is leaked. If rev is omitted, the latest revision on the trunk is Icx^kecL L(x:king prevents 
overlapping changes. A l(x:k is removed with ei or res -u (see below). 

unl(x;ks the revisitm with number rev. If a branch is given, the latest revision on that 
branch is uni(x:ked. If rev is omitted, the latest l(x;k held by the caller is removed. Nor¬ 
mally, only the l(x;ker of a revision may unlock it Somelxxly else unlocking a revision 
breaks the l<x:k. This causes a mail message to be sent to the original locker. The mes¬ 
sage contains a conunentary solicited firom the breaker. The commentary is terminated 
with a line ccHitainmg a single *.*. 

sets l(x;king to striet. Strict locking means that the owner of an RCS file is not exempt 
from locking for checkin. This option should be used for files that are shared. 

sets leaking to non-stricL Non-strict l(x;king means that the owno* of a file need not l(x:k a 
revision for checkin. This option should NOT be used for files that are shared. The 
defitult (-L or -U) is determined by your system administrator. 

1 

ass(x;iates the symbolic name name with the branch or revision rev. Res prints an error 
message if name is already ass(x;iated with anotho^ number. If rev is omitted, the sym¬ 
bolic name is deleted 


-N/uime[:rev] 

same as -n, except that it overrides a previous assignment of ncane. 

-orange deletes ("outdates") the revisions givra by range. A range consisting of a single revision 
numbCT means that revision. A range consisting of a branch number means the latest revi¬ 
sion on that branch. A range of the form revl-rev2 means revisions revl to rev2 on the 
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same branch, -rev means from the beginning of the branch containing rev up to and 
including rev, and rev- means from revision rev to the end of the branch containing rev. 
None of the outdated revisions may have branches or locks. 

-q quiet mode; diagnostics are not printed. 

-sstate[:rev] sets the state attribute of the revision rev to state. If rev is omitted, the latest revision on 
the trunk is assumed; If rev is a branch number, the latest revision on that branch is 
assumed. Any identifier is acceptable for state. A useful set of states is Exp (for experi- 
moital). Stab (for stable), and Rel (for released). By default, ci sets the state of a revision 
to Ejqj. 

-4[tx0le] writes descriptive text into the RCS file (deletes the existing text). If tx^le is omitted, res 
prompts the user for text supplied from the std. input, terminated with a line containing a 
single Otherwise, the descriptive text is copied from the file txtfUe. If the -i option is 
present, descriptive text is requested even if -t is not given. The prompt is suppressed if 
the std. input is not a terminal. 

DIAGNOSTICS 

The RCS file name and the revisions outdated are written to the diagnostic output The exit status 
always refers to the last RCS file operated upon, and is 0 if the operation was successful, 1 otherwise. 

FILES 

The caller of the command must have read/write permission for the directory containing the RCS file 
and read permission for the RCS file itself. Res creates a semaphore file in the same directory as the 
RCS file to prevent simultaneous update. For changes, res always creates a new file. On successful 
completion, res deletes the old one and renames the new one. This strategy makes links to RCS files 
useless. 

IDENTinCATION 

Author Walter F. Tichy, Purdue University, West Lafayette, IN, 47907. 

Revision Numbw: 3.1 ; Release Date: 83A)4/04 . 

Copyright © 1982 by Walter F. Tichy. 

SEE ALSO 

CO (1), ci (1), ident(l), resdiff (1), resmerge (1), rtog (1), resfile (5). 

Walter F. Tichy, "Design, Implementation, and Evaluation of a Revision Control System," in Proeeed- 
ings of the 6th International Conferenee on Software Engineering y IEEE, Tokyo, Sept 1982. 

BUGS 
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NAME 

rcsdiff - compare RCS revisions 
SYNOPSIS 

rcsdiff [ -b ] [ -cefhn ] [ -rrcvi ] [ -rrev2 ] file ... 

DESCRIPTION 

Rcsdiff runs diff (1) to ccHnpare two revisions of each RCS file given. A file name ending in ’,v’ is an 
RCS file name, otherwise a working file name. Rcsdff d^ves the working file name from the RCS file 
name and vice versa, as explained in co (1). Pairs consisting of both an RCS and a working file name 
may also be specified. 

The options -b, -c, -e, -f, and -h have the same effect as described in diff (1); option -n generates an 
edit script of the format used by RCS. 

If both revl and rev2 are omitted, rcsdiff compares the latest revision on the trunk with the contents of 
the corresponding working file. This is useful for determining what you changed since the last checkin. 

If revl is given, but rev2 is omitted, rcsdff compares revision revl of the RCS file with the contents of 
the corresponding working file. 

If both revl and rev2 are given, rcsdiff comp 2 ies revisions revl and rev2 of the RCS file. 

Both revl and rev2 may be given numerically or symbolically. 

EXAMPLES 

The command 

rcsdiff f.c 

runs diff on the latest trunk revision of RCS file f.c,v and the contents of working file f.c. 
IDENTIFICATION 

Author Walter F. Tichy, Purdue University, West Lafayette, IN, 47907. 

Revision Number 3.0 ; Release Date: 83/01/15 . 

Copyright © 1982 by Walter F. Tichy. 

SEE ALSO 

ci (1), CO (1), diff (1), idem (1), res (1), resmerge (1), rlog (1), resfile (5). 

WaltCT F. Tichy, "Design, Implementation, and Evaluation of a Revision Control System," in Proceed¬ 
ings of the 6th International Conference on Software Engineerings IEEE, Tokyo, SepL 1982. 

BUGS 
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NAME 

rcsfile - fonnat of RCS file 
DESCRIPTION 

An RCS file is an ASCII file. Its contents is described by the grammar below. The text is free format, 
i.e., spaces, tabs and new lines have no significance except in strings. Strings are enclosed by If a 
string contains a *@*, it must be doubled. 

The meta syntax uses the foUowing conventions: M* (bar) separates alternatives; *(’ and enclose opti- 
nal phrases; *(* and *}«* enclose phrases that may be repeated zero or more times; *{' and *}+* enclose 
phr^s that must appear at least once and may be repeated; *<* and *>* enclose nonterminals. 


<rcstext> 


<admin> {<delta>)* <desc> {<deltatext>}* 

<admin> 


head 

{<num>}; 



access 

{<id>)*; 



symbols 

{<id>; <num>)*; 



locks 

{<id>: <nuni>)*; 



comment 

{<string>); 

<delta> 

::= 

<num> 

date 

<num>; 



author 

<id>; 



state 

{<id>); 



branches 

{<num>)’>; 



next 

{<num>}; 

<desc> 

::s: 

desc 

<string> 

<deltatext> 


<num> 




log 

<string> 



text 

<string> 

<num> 


{«ligit>{.})+ 


<digit> 


0 1 1 1 ... 1 9 


<id> 


<letier> {<idchar>) ♦ 

<letter> 


A 1 B 1... IZ 1 a 

1 b 1... 1 z 

<idchar> 


Any printing ASCII characto’ except space, 
tab, carriage return, new line, and <special>. 

<special> 




<string> 


@{any ASCII characta, with doubled) 


Idratifiers are case sensitive. Keywords are in Iowot case only. The sets of keywords and identifiers 
may overlap. 
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The <delta> nodes form a tree. All nodes whose numbers consist of a single pair (e.g., 2.3, 2.1, 1.3, 
etc.) are (HI the "trunk", and are linked through the "next” field in order of decreasing numbers. The 
"head" field in the <admin> node points to the head of that sequence (i.e., contains the highest pair). 


All <delta> nodes whose numbers consist of 2n fields (n^) (e.g., 3.1.1.1, 2.1.2.2, etc.) are linked as fol¬ 
lows. All nodes whose first (2n)-l number fields are identical are linked through the "next" field in 
order of increasing numbo^. For each such sequrace, the <delta> node whose number is identical to 
the first 2(n-l) number fields of die deltas (mi that sequence is called the branchpoint. The "branches" 
field of a node contains a list of the numbers of the ^t nodes of all sequences for which it is a bran¬ 
chpoint This list is ordoed in increasing numbers. 


Example: 


Head 


/ \ 

/ \ 

/ \ 
/1.2.1.3\ 


/ \ 

/ \ 

/ \ 

/ 1 . 2 . 1 . 1 \ 


I 

I 

I 

I 


/ \ 

/ \ 

/ \ 
/1.3.1.1\ 


I 2.1 I 


/ \ 

/ \ 

/ \ 

/ 1 . 2 . 2 . 2 \ 


/ \ 

/ \ 

/ \ 

/ 1 . 2 . 2 . 1 . 1 . 1 \ 


\ 1.3 / 

/ 

\ / 

\ / 


/ \ 

/ \ 

/ \-- 

/ 1 . 2 . 2 . 1 \ 


\ 1.2 / 
-\ /-. 
\ / 

\ / 


V 


\ 1.1 / 
\ / 

\ / 

\ / 


Fig. 1: A revision tree 

IDENTinCATION 

Author Walt» F. Tichy, Purdue University, West Lafayette, IN, 47907. 
Revision Number 3.0 ; Release Date: 82/11/18 . 

Copyright © 1982 by Walter F. Tichy. 
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SEE ALSO 

d (1), CO (1), idem (1), res (1), icsdiff (1), resmerge (1), riog (1). 
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NAME 

rcsmerge - merge RCS revisions 
SYNOPSIS 

rcsmerge -rrevl [ -rrev2 ] [ -p ] file 
DESCRIPTION 

Rcsmerge incorporates the changes between revl and rev2 of an RCS file into the corresponding work¬ 
ing file. If -p is given, the result is printed on the std. ouq}ut, oth^^ise the result overwrites the work¬ 
ing file. 

A file name ending in ’,v’ is an RCS file name, otherwise a working file name. Merge drives the work¬ 
ing file name from the RCS file name and vice vorsa, as explained in co (1). A pair consisting of both 
an RCS and a working file name may also be specified. 

Revl may not be omitted. If revl is omitted, the l^est revision on the trunk is assumed. Both revl and 
revl may be given numerically or symbolically. 

Rcsmerge prints a warning if there are overlaps, and delimits the overlapping regions as explained in co 
-j. The command is useful for incorporating changes into a checked-out revision. 

EXAMPLES 

Suppose you have released revision 2.8 of f.c. Assume furthermore that you just completed revision 3.4, 
when you receive updates to release 2.8 from someone else. To combine the updates to 2.8 and your 
changes between 2.8 and 3.4, put the updates to 2.8 into file f.c and execute 

rcsmerge -p -r2.8 -r3.4 f.c >f.mCTged.c 

Then examine f.merged.c. Alternatively, if you want to save the updates to 2.8 in the RCS file, check 
them in as revision 2.8.1.1 and execute co -j: 

ci -r2.8.1.1 f.c 
CO -r3.4 -j2.8:2.8.1.1 f.c 

As another example, the following command undoes the changes between revision 2.4 and 2.8 in your 
currently checked out revision in f.c. 

rcsmerge -r2.8 -r2.4 f.c 

Note the order of the arguments, and that f.c will be overwritten. 

IDENTIFICATION 

Author Walter F. Tichy, Purdue UnivCTsity, West Lafayette, IN, 47907. 

Revision Number 3.0 ; Release Date: 83/01/15 . 

Copyright © 1982 by Walter F. Tichy. 

SEE ALSO 

ci (1), CO (1), merge (1), idem (1), res (1), resdiff (1), riog (1), resfile (5). 

WaltCT F. Tichy, "Design, Implementation, and Evaluation of a Revision Control System," in Proceed¬ 
ings of the 6th International Conference on Software Engineerings IEEE, Tokyo, Sept 1982. 

BUGS 

Rcsmerge does nm work for files that contain lines with a single 
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NAME 

rdist - remote file distribution program 
SYNOPSIS 

rdist [ -nqbRhivwy ] [ -f distfile ] [ -d var^value ] [ -m host ] [ name ... ] 
rdist [ -nqbRhivwy ] -c name ... [login@]host[:dest] 

DESCRIPTION 

Rdist is a program to maintain identical copies of files over multiple hosts. It preserves the owner, 
group, mode, and mtime of files if possible and can update programs that are executing. Rdist reads 
commands fiom distfile to direct the updating of files and/or directories. If distfile is the standard 
input is used. If no -f option is present, the program looks first for ‘distfile’, ien ‘Distfile’ to use as 
the input If no names are specified on the command line, rdist will update all of the files and direc¬ 
tories listed in distfile. Otherwise, the argument is taken to be the name of a file to be updated or the 
label of a command to execute. If label and file names conflict it is assumed to be a label. These may 
be used together to update specific files using specific commands. 

The -c option forces rdist to interpret the remaining arguments as a small distfile. The equivalent 
distfile is as follows. 

( name ...) -> [login@]host 
install [dest] ; 


Other options: 

-d Define var to have value. The -d option is used to define or override variable definitions in 
the distfile. Value can be the emj^ string, one name, or a list of names surrounded by 
parentheses and separated by tabs and/or spaces. 

-m Limit which machines are to be updated. Multiple -m arguments can be given to limit updates 
to a subset of the hosts listed the distfile. 

-n Print the commands without executing them. This option is useful for debugging distfile. 

-q Quiet mode. Files that are being modified are normally printed on standard output. The -q 

option suppresses this. 

-R Remove extraneous files. If a directory is being updated, any files that exist on the remote host 
that do not exist in the master directory are removed. This is useful for maintaining truely 
identical copies of directories. 

-h Follow symbolic links. Cc^y the file that the link points to rather than the link itself. 

—i Ignore unresolved links. Rdist will normally try to maintain the link structure of files being 

transfixed and warn the user if all the links cannot be found. 

-v Verify that the files are up to date on all the hosts. Any files that are out of date will be 
displayed but no files will be changed nor any mail sent 

-w Whole mode. The whole file name is aj^nded to the destination directory name. Normally, 
only the last component of a name is u^ when renaming files. This will preserve the direc¬ 
tory structore of the files being copied instead of flattening the directory structure. For exam¬ 
ple, renaming a list of files such as ( dirl/fl dir2/f2 ) to dir3 would create files dir3/dirl/fl and 
dir3/dir2^ instead of dir3/fl and dir3/f2. 

-y Younger mode. Files are normally updated if their mdme and size (see stati^) disagree. The 
-y option causes rdist not to update files that are younger than the master copy. This can be 
used to prevent newx copies on other hosts firom being replaced. A warning message is 
printed for files which are newer than the mastx copy. 
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-b Binary comparison. Perfcnm a binary ccmiparison and update files if they differ rather than 
comparing dates and sizes. 

Dis^le contains a sequ^ce of entries that specify the files to be copied, the destination hosts, and what 
operations to perform to do the updating. Each entry has one of the following formats. 

<variable name> *=’ <name list> 

[ label: ] <source list> *->’ <destination lisl> <command list> 

[ label: ] <source list> <time_stamp file> <command list> 

The first format is used for defining variables. The second format is used for distributing files to other 
hosts. The third format is used for making lists of files that have been changed since some given date. 
The source list specifies a list of files and/or directories on the local host which are to be used as the 
mast^ copy fca: distribution. The destination list is the list of hosts to which these files are to be 
copied. Each file in the source list is added to a list of changes if the file is out of date on the host 
which is being updated (second format) or the file is newer than the time stamp file (third format). 

Labels are optional. They are used to identify a command for partial updates. 

Newlines, tabs, and blanks are only used as separators and are otherwise ignored. Comments begin with 
’#’ and end with a newline. 

Variables to be expanded begin with *$’ followed by one character or a name enclosed in curly braces 
(see the examples at the end). 

The source and destination lists have the following format: 

<name> 

or 

‘(’ <zero or more names separated by white-space> *)’ 

The shell meta-characters *[’. ‘1’. *{’. and *?’ are recognized and expanded (on the local host 

only) in the same way as csh(l). They can be escaped with a backslash. The character is also 
expanded in the same way as csh but is expanded separately on the local and destination hosts. When 
the -w option is used with a file name that begins with everything except the home directory is 
appended to the destination name. File names which do not begin with 7’ or use the destination 
user’s home directory as the root directory for the rest of the file name. 

The command list consists of zero or more commands of the following format. 

‘install’ <options> opt_dest_name 
‘notify’ <name list> ‘;’ 

‘except’ <name list> ‘;’ 

‘except_pat’ cpattem list>‘;’ 

‘special’ <name liso string ‘;’ 

The install command is used to copy out of date files and/or directories. Each source file is copied to 
each host in the destination list Directories are recursively copied in the same way. Opt_dest_name is 
an optional parameter to rename files. If no instcUl command appears in the command list or the desti¬ 
nation name is not specified, the source file name is used. Directories in the path name will be created 
if they do not exist on the remote host. To help prevent disastors, a non-empty directory on a target 
host will never be replaced with a regular file or a symbolic link. However, under the ‘-R’ option a 
non-empty directory will be removed if the corresponding filename is completely absent on the master 
host The options are ‘-R’, ‘-h’, ‘-i’, ‘-v’, ‘-w’, ‘-y’, and ‘-b’ and have the same semantics as options 
on the command line except they only apply to the files in the source list The login name used on the 
destination host is the same as the local host unless the destination name is of the format “login@host". 
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The notify cranmand is used to mail the list of files updated (and any errors that may have occured) to 
the listed names. If no appears in the name, the destination host is ^}pended to the name (e.g., 
namel@host, name2@host,...). 

The except command is used to update all of the files in the source list except for the files listed in 
name list. This is usually used to c(^y everything in a directory except certain files. 

The except_pat command is like the except command except that pattern list is a list of reg ular expres¬ 
sions (see ed(l) for details). If one of the pattans matches some string within a file name, that file will 
be ignored. Note that since V is a quote character, it must be doubled to become part of the regular 
expressicHi. Variables are expanded in pattern list but not shell file pattern matching characters. To 
include a *$’, it must be escaped with V. 

The special command is used to specify sh(l) commands that are to be executed on the remote host 
after the file in name list is updated or installed. If the name list is omitted then the shell commands 
will be executed for every file updated or installed. The shell variable ‘FILE’ is set to the current 
filename before executing the commands in string. String starts and ends with and can cross multi¬ 
ple lines in distfile. Multiple commands to the shell should be separated by Commands are exe¬ 
cuted in the user’s home directory on the host being updated. The special command can be used to 
rebuild private databases, etc. after a program has been updated. 

The following is a small example. 

HOSTS = ( matisse root(2)arpa) 

FILES = (/bin /lib /usr/bin /usr/games 

/usrAnclude/ {* .h, {stand,sys,vax* ,pascal 4 nachine )/♦ .h} 

/usr/lib /usr/man/man? /usr/ucb /usr/local/rdist) 

EXLIB ss ( MaiLrc aliases aliases.cfir aliases.pag crontab dshrc 

sendmail.cf sendmail.fc sendmaiLhf sradmail.st uucp vfont) 

S{FILES}->${HOSTS} 
install -R ; 

except/usr/lib/${EXLIB) ; 
except /usr/games/lib ; 

special /usr/lib/sendmail "/usr/lib/sendmail -bz" ; 


srcs: 

/usr/src/bin -> arpa 

exccpt_pat (\\o\$ /SCCSNS ); 

IMAGEN = (ips dviimp catdvi) 

imagen: 

/usr/local/${IMAGEN) -> arpa 
install /usr/local/lib ; 
notify ralph ; 

S(FILES) :: stamp.cory 

notify rooii@cory ; 


FILES 

distfile input command file 
/unp/rdisf^ temporary file for update lists 
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SEE ALSO 

sh(l), csh(l), stat(2) 

DIAGNOSTICS 

A complaint about mismatch of rdist version numbers may really stem from some problem with starting 
your shell, e.g., you are in too many groups. 

BUGS 

Source files must reside on the local host where rdist is executed. 

There is no easy way to have a special command executed after all files in a directory have been 
updated. 

Variable expansion only works for name lists; th^ should be a general macro facility. 

Rdist aborts on files which have a negative mtime (before Jan 1, 1970). 

There should be a ‘force’ option to allow replacement of non-empty directories by regular files or sym- 
links. A means of updating file modes and owners of otherwise identical files is also needed. 


April 21,1989 


The Wollongong Group 


4 



REFER(l) 


UNIX Programmer’s Manual 


REFER(l) 


NAME 

refer - find and insert literature references in documents 
SYNOPSIS 

refer [ -a ] [ -b ] [ -c ] [ -e ] [ -fn ] [ -kx ] [ -lm,n ] [ -n ] [ -p bib ] [ skeys ] [ -B/.m ] [ -p ] [ -S 
] [ file ... ] 

DESCRIPTION 

Re/er is a {ffeprocessor for nroff or trqff{X) that finds and formats references for foomotes or endnotes. 
It is also the base for a smes of {Hograms designed to index, search, sort, and print stand-alone 
bibliographies, or other data entered in the appropriate form. 

Given an incomplete citation with sufficiently precise keywords, refer will search a bibliographic data¬ 
base for references containing these keywords anywho^ in the title, author, journal, etc. The input file 
(or standard input) is copied to standard output, except for lines between .[ and .] delimiters, which are 
assumed to contain keywords, and are replaced by information finom the bibliographic database. The 
user may also search different databases, override particular fields, or add new fields. The reference 
data, from whatever source, are assigned to a set of troff strings. Macro packages such as ms(J) print 
the finished reference text from these strings. By default references are flagged by footnote numbers. 

The following options are available: 

-an Reverse the first n author names (Jones, J. A. instead of J. A. Jones). If n is omitted all author 
names are reversed. 

-b Bare mode: do not put any flags in text (neither numb^ nor labels). 

-ckeys Capitalize (with Caps Small Caps) the fields whose key-letters are in keys. 

-€ Instead of leaving the references where encountered, accumulate them until a sequence of the 
form 

.[ 

$LIST$ 

.] 

is encountered, and then write out all references collected so far. Collapse references to same 
source. 

-fn Set the footnote number to n instead of the default of 1 (one). With labels rather than numbers, 
this flag is a no-op. 

-kx Instead of numbering references, use labels as specified in a reference data line beginning %x; 
by default x is L. 

-Ini,n Instead of numbering references, use labels made fiwm the senior author’s last name and the 
year of publication. Only the first m letters of the last name and the last n digits of the date are 
used. If either m or n is omitted the entire name or date respectively is used. 

-n Do not search the default file /usr/dict^apers/Ind. If thwe is a REFER environment variable, the 
specified file will be searched instead of the default file; in this case the -n flag has no effect 

-p bib 

Take the next argument bib as a file of ref^nces to be searched. The default file is searched 
last 

skeys Sort references by fields whose key-letters are in the keys string; permute reference numbers in 
text accordingly. Implies -e. The key-letters in keys may be followed by a number to indicate 
how many such fields are used, with + taken as a vay large number. The default is AD which 
sorts on the senior author and then date; to sort for example, on all authors and then title, use - 
sA+T. 

-Bl.m Bibliography mode. Take a file composed of records separated by blank lines, and turn them 
into trcff input Label / will be turned into the macro .m with / defaulting to %X and .m 
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defaulting to AP (annotation paragraph). 

-P Place punctuation marks after the reference signal, rather than before. (Periods and com¬ 
mas used to be done with strings.) 

-S Produce references in the Natural or Social Science format. 

To use your own references, put them in the fcrmat described below. They can be searched more 
rapidly by running indxbib{\) on them before using refer; failure to index results in a linear search. 
When r^er is used with the eqn, neqn or tbl preprocessors refer should be first, to minimize the volume 
of data passed through pipes. 

The refer preprocessor and associated programs expect input firom a file of references composed of 
records separated by blank lines. A record is a set of lines (fields), each containing one kind of infor¬ 
mation. Fields start on a line beginning with a followed by a key-letter, then a blank, and finally 
the contents of the field, and continue until the next line starting with The output ordering and 

formatting of fields is controlled by the macros specified for nroffitroff (for footnotes and endnotes) or 
roffbib (for stand-alone bibliographies). For a list of the most common key-letters and their correspond¬ 
ing fields, see addbib(\). An example of a refer entry is given below. 

EXAMPLE 

%A M. E. Lesk 

%T Some Applications of Inverted Indexes (Mi the UNIX System 

%B UNIX Programma‘’s Manual 

%V 2b 

%I Bell Laboratcvies 

%C Murray Hill, NJ 

%D 1978 

FILES 

/usr/dict/papers directory of default publication lists 
/usr/lib/refer directory of companion programs 

SEE ALSO 

addbib(l), sortbib(l), roffbib(l), indxbib(l), lookbib(l) 

AUTHOR 

Mike Lesk 

BUGS 

Blank spaces at the end of lines in bibliography fields wiU cause the records to sort and reverse 
incorrectly. Sorting large numb^ of references causes a core dump. 
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NAME 

remote — remote host description file 
DESCRIPTION 

The systems known by tip{lC) and their attributes are stored in an ASCII file which is struc¬ 
tured somewhat like the termcap(S) file. Each line in the file provides a description for a sin- 
^ system. Fields are separated by a colon Lines ending in a \ charaaer with an 

immediately following newline are continued on the next line. 

The first entry is the name(s) of the host system. If there is more than one name for a system, 
the names are separated by vertical bars. After the name of the system comes the fields of the 
description. A ^Id name followed by an *»’ sign indicates a string value follows. A field 
name followed by a ‘# ’ sign indicates a following numeric value. 

Entries named “tip*” and “cu*** are used as default entries by r/p, and the cu interface to fzp, 
as follows. When t^ is invoked with only a phone number, it looks for an entry of the form 
“tipSOO**, where 300 is the baud rate with which the conneaion is to be made. When the cu 
interface is used, entries of the form “cu300** are used. 


CAPABILITIES 

Capabilities are either strings (str), numbers (num), or boolean flags (bool). A string capabil¬ 
ity is specified by capability^value; e.g. “dv=/dev/harris”. A numeric capability is specified by 
capabilityit value; e.g. ‘"xa# 99”. A boolean capability is specified by simply listing the capabil- 
ity. 

at (sir) Auto call unit type. 

hr (num) The baud rate used in establishing a connection to the remote host. This is a 
dedmal number. The default baud rate is 300 baud. 

cm (str) An initial connection message to be sent to the remote host. For example, if a 
host is reached through port selector, this might be set to the appropriate sequence 
required to switch to the host. 


cu 

di 

du 

dv 


d 

fs 

hd 

ie 

oe 


(str) Call unit if making a phone call. Default is the same as the *dv’ field. 

(str) Disconnea message sent to the host when a disconnea is requested by the user, 
(bool) This host is on a dial-up line. 

(str) UNIX device(s) to open to establish a conneaion. If this file refers to a terminal 
line, /zp(lC) attempts to perform an exclusive open on the device to insure only one 
user at a time has access to the pon. 

(str) Charaaers marking an end-of-line. The default is NULL. *"* escapes are only 
recognized by tip after one of the charaaers in ‘el’, or after a carriage-return. 

(str) Frame size for transfers. The default frame size is equal to BUFSIZ. 

(bool) The host uses half-duplex communication, local echo should be performed. 

(str) Input end-of-file marks. The default is NULL. 

(str) Output end-of-file string. The default is NULL. When t^ is transferring a file, 
this string is sent at end-of-file. 


pa (str) The type of parity to use when sending data to the host. This may be one of 
“even”, “odd” “none”, “zero” (always set bit 8 to zero), “one” (always set bit 8 to 1). 
The default is even parity. 

pn (str) Telephone number(s) for this host. If the telephone number field contains an (2) 
sign, tip searches the file letcjphones file for a list of telephone numbers; c.f. phonesiS). 

tc (str) Indicates that the list of capabilities is continued in the named description. This 
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Here is a short example showing the use of the capability contiiniation feature: 
UNIX-1200:\ 

:dv=/<Iev/cau0:el=''D*U"CrS*Q*O@:du:rtt=ventel:ie=#$%:oe='‘D:bi#1200: 

arpavaxlax:\ 

:pn*7654321%:tc=UNIX-1200 

FILES 

/etc/remote 

SEE ALSO 

tqKlQt ph(Hies(S) 
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NAME 

rev - reverse lines of a file 

SYNOPSIS 

rev [ file ] ... 

DESCRIPTION 

Rev copies the named files to the standard output, reversing the order of characters in every line. If no 
file is specified, the standard input is copied. 
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NAME 

rlog - print log messages and other information about RCS files 

SYNOPSIS 

rlog [ options ] file ... 

DESCRIPTION 

Rlog prints information about RCS files. Files ending in ‘,v’ are RCS files, all others are working files. 
If a working file is given, rlog tries to find the corresponding RCS file first in directory ./RCS and then 
in the current directory, as explained in co (1). 

Rlog prints the following information for each RCS file: RCS file name, working file name, head (i.e., 
the number of the latest revision on the trunk), access list, locks, symbolic names, suffix, total number 
of revisions, number of revisions selected for printing, and descriptive text. This is followed by entries 
for the selected revisions in reverse chronological order for each branch. For each revision, rlog prints 
revision number, author, date/time, state, number of lines added/deleted (with respect to the previous 
revisi(Mi), locker of the revision (if any), and log message. Without options, rlog prints complete infor¬ 
mation. The options below restrict this output 

-L ignOTes RCS files that have no locks set; convenient in combination with -R, -h, or -1. 

-R only prints the name of the RCS file; convenient for translating a working file name into an 

RCS file name. 

-h prints only RCS file name, working file name, head, access list, locks, symbolic names, and 

suffix. 

-t prints the same as -h, plus the descriptive text 

-ddates prints information about revisions with a checkin date/time in the ranges given by the 
semicolon-separated list of dates. A range of the form dl<d2 or d2>d2 selects the revisions 
that were deposited between dl and d2, (inclusive). A range of the form <d or d> selects 
all revisions dated d or earlier. A range of the form d< or >d selects all revisions dated d 
or lata. A range of the form d selects the single, latest revision dated d or earlier. The 
date/time strings d, dl, and d2 are in the free format explained in co (1). Quoting is nor¬ 
mally necessary, especially for < and >. Note that the separator is a semicolon. 

-lUockers] prints information about locked revisions. If the comma-separated list lockers of login 
names is given, only the revisions locked by the given login names are printed. If the Ust 
is omitted, all locked revisions are printed. 

-vrevisions prints information about revisions giv«i in the comma-separated list revisions of revisions 
and ranges. A range revl-rev2 means revisions revl to rev2 on the same branch, -rev 
means revisions from the beginning of the branch up to and including rev, and rev- means 
revisions starting with rev to the end of the branch containing rev. An argument that is a 
branch means all revisions on that branch. A range of branches means all revisions on the 
branches m that range. 

-estates prints information about revisions whose state attributes match one of the states given in the 
comma-separated list states. 

-wilogins] prints information about revisions checked in by users with login names appearing in the 
comma-separated list logins. If logins is omitted, the user’s login is assumed. 

Rlog prints the intersection of the revisions selected with the options -d, -1, -s, -w, intersected with the 
union of the revisions selected by -b and -r. 

EXAMPLES 

rlog -L -R RCS/*,v 
rlog -L -h RCS/*,v 
rlog -L -1 RCS/*,v 
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rlog RCS/*,v 


The first command prints the names of all RCS files in the subdirectory ‘RCS’ which have locks. The 
second command prints the headers of those files, and the third prints the headers plus the log messages 
of the locked revisions. The last command prints complete information. 

DIAGNOSTICS 

The exit status always refers to the last RCS file operated upon, and is 0 if the operation was success¬ 
ful, 1 otherwise. 

IDENTIFICATION 

Author Walter F. Tichy, Purdue Univasity, West Lafayette, IN, 47907. 

Revision Number 3.2 ; Release Date: 83/05/11 . 

Copyright © 1982 by Walter F. Tichy. 

SEE ALSO 

ci (1), CO (1), ident(l), res (1), resdiff (1), resmerge (1), resfile (5). 

Walter F. Tichy, "Design, Implementation, and Evaluation of a Revision Control System," in Proceed¬ 
ings of the 6th International Conference on Softweare Engineering, IEEE, Tokyo, SepL 1982. 

BUGS 
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NOTE 

WOLLONGONG’S WIN/TCP PRODUCT 


NAME 

rlogin - remote login 
SYNOPSIS 

rlogin rhost [ -ec ] [ -S ] [ -L ] [ -1 username ] 
rhost [ -ec ] [ -8 ] [ -L ] [ -1 username ] 

DESCRIPTION 

Rlogin connects your terminal on the current local host system Ihost to the remote host system rhost. 

Each host has a file letclhosts.eqmv which contains a list of rhost's with which it shares account names. 
(The host names must be the standard names as described in rj/i(lC).) When you rlogin as the same 
user on an equival^it host, you dcMi’t need to give a password. Each user may also have a private 
equivalence list in a file j'hosts in his login directory. Each line in this file should contain an rhost and 
a username separated by a space, giving additional cases wh^ logins without passwords are to be per¬ 
mitted. If the originating user is not equivalent to the remote user, then a login and password will be 
prompted for on the remote machine as in login{\). To avoid some security problems, the .rhosts file 
must be owned by eith^ the remote usw or root 

The remote terminal type is the same as your local terminal type (as given in your environment TERM 
variable). The terminal or window size is also copied to the remote system if the server supports the 
option, and changes in size are reflected as well. All echoing takes place at the remote site, so that 
(except for delays) the rlogin is transparent. Flow control via "S and "Q and flushing of input and out¬ 
put on interrupts are handled properly. The optional argument -8 allows an eight-bit input data path at 
all times; othawise parity bits are stripped except when the remote side’s stop and start characters are 
other than "SrQ. The argument -L allows the rlogin session to be run in litout mode. A line of the 
form disconnects from the remote host, wh^e is the escape character. Similarly, the line 
““*Z” (where "Z, control-Z, is the suspend character) will suspend the rlogin session. Substitution of 
the delayed-suspend character (normally 'Y) for the suspend character suspends the send portion of the 
rlogin, but allows output from the remote system. A different escape character may be specified by the 
-e option. There is no space separating this option flag and the argument character. 

EUNICE NOTES 

This file is pertinent only to customers who have Wollongong’s WIN/TCP product 

SEE ALSO 

rsh(lQ 

FILES 

/usr/hosts/* for rhost version of the command 

BUGS 

More of the environment should be propagated. 
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NAME 

rm, rmdir - remove (unlink) files or directories 
SYNOPSIS 

rm [-f] [-r] [-i] [-] file... 
rmdir dir... 

DESCRIPTION 

Rm removes the entries for one or more files from a directory. If an entry was the last link to the file, 
the file is destroyed. Removal of a file requires write permission in its directory, but neither read nor 
write permission on the file itself. 

If a file has no write permission and the standard input is a terminal, its permissions are printed and a 
line is read from the standard input If that line begins with ‘y’ the file is deleted, otherwise the file 
remains. No questions are asked and no errors are reported when the -f (force) option is given. 

If a designated file is a directory, an error comment is printed unless the optional argument -r has been 
used. In that case, rm recursively deletes the entire contents of the specified directory, and the directory 
itself. 

If the -i (interactive) option is in effect, rm asks whether to delete each file, and, under -r, whether to 
examine each directory. 

The null option - indicates that all the arguments following it are to be treated as file names. This 
allows the specification of file names starting with a minus. 

Rmdir removes entries for the named directories, which must be empty. 

SEE ALSO 

rm(l), unlink(2), rmdir(2) 
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NAME 

rmail - handle remote mail received via uucp 

SYNOPSIS 

rmail user... 

DESCRIPTION 

RmcUl interprets incoming mail received via uucp(lC), collapsing “From” lines in the form generated 
by binmailiX) into a single line of the form “return-path!sender”, and passing the processed mail on to 
sendmail{S). 

Rmail is explicitly designed for use with uucp and sendmail. 

SEE ALSO 

binmail(l), uucp(lC), sendmail(8) 

BUGS 

Rmail should not reside in /bin. 
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NAME 

rmdir, rm - remove (unlink) directories or files 

SYNOPSIS 

rmdir dir... 

rm[-f][-r ][-!][-] file... 

DESCRIPTION 

Rmdir removes entries for the named directOTies, which must be empty. 

Rm removes the entries for one or more files from a directory. If an entry was the last link to the file, 
the file is destroyed. Removal of a file requires write permission in its directory, but neither read nor 
write permission on the file itself. 

If a file has no write permission and the standard input is a terminal, its permissions are printed and a 
line is read from the standard input If that line begins with *y’ the file is deleted, otherwise the file 
remains. No questions are asked and no errors are reported when the -f (force) option is given. 

If a designated file is a directory, an error comment is printed unless the optional argument -r has been 
used- In that case, rm recursively deletes the entire contents of the specified directory, and the directory 
itself. 

If the -i (interactive) option is in effect, rm asks whether to delete each file, and, under -r, whether to 
examine each directory. 

The null option - indicates that all the argumrats following it are to be treated as file names. This 
allows the specification of file names starting with a minus. 

SEE ALSO 

rm(l), unlink(2), rmdir(2) 
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NAME 

roffbib - run off bibliographic database 
SYNOPSIS 

roffbib [ -e ] [ -h ] [ -n ] [ -o ] [ -r ] [ -s ] [ -Tterm ] [ -x ] [ -m mac ] [ -V ] [ -Q ] [ file ... ] 
DESCRIPTION 

Roffbib prints out all records in a bibliographic database, in bibliography format rather than as foomotes 
or endnotes. Generally it is used in conjunction with sortbib: 

sortbib database I roffbib 

Roffbib accepts most of the options understood by nroff{\), most importantly the -T flag to specify ter¬ 
minal type. 

If abstracts or comments are entered following the %X field key, roffbib will format them into para¬ 
graphs for an annotated bibliography. Several %X fields may be given if several annotation paragraphs 
are desired. The ~x flag will suppress the printing of these abstracts. 

A user-defined set of macros may be specified after the -m option. There should be a space between 
the -m and the macro filename. This set of macros will replace the ones defined in 
/usr/lib/tmac/tmac.bib. The -V flag will send output to the Versatec; the -Q flag will queue output for 
the phototypesetter. 

Four command-line registers control formatting style of the bibliography, much like the number regis¬ 
ters of ms(7). The command-line argument -rNl will number the ref^ences starting at one (1). The 
flag -rV2 will double space the bibliography, while nrVI will double space references but single space 
annotation paragraphs. The line length can be changed from the default 6.5 inches to 6 inches with the 
-rL6i argument, and the page offset can be set from the default of 0 to one inch by specifying -rOli 
(capital 0, not zero). Note: with the -V and -Q flags the default page offset is already one inch. 

FILES 

/usr/lib/tmac/tmac.bib file of macros used by nroff/troff 
SEE ALSO 

refer(l), addbib(l), sortbib(l), indxbib(l), lookbib(l) 

BUGS 

Users have to rewrite macros to create customized formats. 
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NAME 

rsh - remote shell 
SYNOPSIS 

rsh host [ -1 username ] [ -n ] command 
host [ -1 username ] [ -n ] command 

DESCRIPTION 

Rsh connects to the specified host, and executes the specified command. Rsh copies its standard input 
to the remote command, the standard output of the r^ote command to its standard output, and the 
standard error of the remote command to its standard error. Interrupt, quit and terminate signals are 
propagated to the remote command; rsh normally terminates when the remote command does. 

The remote username used is the same as your local username, unless you specify a different remote 
name with the -4 option. This remote name must be equivalent (in the sense of rloginilC)) to the ori¬ 
ginating account; no provision is made for specifying a password with a command. 

If you omit command, then instead of executing a single command, you will be logged in on the remote 
host using rlogin{\C). 

Shell metacharacters which are not quoted are interpreted on local machine, while quoted metacharac¬ 
ters are int^reted on the remote machine. Thus the command 

rsh otherhost cat remotefile » localfile 

appends the remote file remotefile to the localfile localfile, while 

rsh otherhost cat remotefile "»" othenemotefile 

appends remotefile to otherremotefile. 

Host names are given in the file /etc/hosts. Each host has one standard name (the first name given in 
the file), which is rather long and unambiguous, and optionally one or more nicknames. The host 
names for local machines are also commands in the directory ^sr/hosts; if you put this directory in 
your search path then the rsh can be omitted. 

EUNICE NOTES 

This file is pertinent only to customers who have Wollongong’s WIN/TCP product 

FILES 

/etc/hosts 

/usr/hosts/* 

SEE ALSO 

rlogin(lQ 

BUGS 

If you are using csh(l) and put a rj/i(lC) in the background without redirecting its input away firom the 
terminal, it will block even if no reads are posted by the remote command. If no input is desired you 
should redirect the input of rsh to /dev/nuU using the -n optitm. 

You caimot run an interactive command (like rogue{6) or vi(l)); use rlogin{\C). 

Stop signals stop the local rsh process only; this is arguably wrong, but currently hard to fix for reasons 
too complicated to explain here. 
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NAME 

ruptime - show host status of local machines 
SYNOPSIS 

ruptime [ -a ] [ -r ] [~l] [ -t ] [ -u ] 

DESCRIPTION 

Ruptime gives a status line like uptime for each machine on the local network; these are formed from 
packets broadcast by each host on the netw(M‘k once a minute. 

Machines for which no status report has been received for 11 minutes are shown as being down. 

Users idle an hour or more are not counted unless the -a flag is given. 

Normally, the listing is sorted by host name. The -1, -t, and -u flags specify sorting by load average, 
uptime, and number of users, respectively. The -r flag reverses the sort order. 

EUNICE NOTES 

This file is pertinent only to customers who have Wollongong’s WIN/TCP product 

FILES 

/usr/spool/rwho/whod.* data files 

SEE ALSO 

rwho(lC) 
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NAME 

rwho - who’s logged in on local machines 

SYNOPSIS 

rwho [ -a ] 

DESCRIPTION 

The rwho command produces output similar to who, but for all machines on the local network. If no 
report has been received from a machine for 5 minutes then rwho assumes the machine is down, and 
does not report users last known to be logged into that machine. 

If a users hasn’t typed to the system for a minute or more, then rwho reports this idle time. If a user 
hasn’t typed to the system for an hour or more, then the user will be omitted from the output of rwho 
unless the -a flag is given. 

EUNICE NOTES 

This file is pertinent only to customers who have Wollongong’s WIN/TCP product 

FILES 

/usr/spool/rwho/whod.* information about other machines 
SEE ALSO 

ruptime(lC), rwhod(8C) 

BUGS 

This is unwieldy when the number of machines on the local net is large. 


April 24, 1989 


The Wollongong Group 


1 



SCCS(l) 


UNIX Programmer’s Manual 


SCCS(l) 


NAME 

sees - front end for the SCCS subsystem 
SYNOPSIS 

sees [ -r ] [ -dpath ] [ -ppath ] eommand [ flags ] [ args ] 

DESCRIPTION 

Sees is a front end to the SCCS programs that helps them mesh more eleanly with the rest of UNIX. It 
also ineludes the eapabiUty to run ‘*set user id” to another user to provide additional proteetion. 

Basieally, sees runs the eommand with the speeified flags and args. Each argument is normally modified 
to be prepended with “SCCS/s.”. 

Flags to be interpreted by the sees program must be before the eommand argument Flags to be passed 
to the actual SCCS program must come after the eommand argument These flags are specific to the 
command and are discussed in the documentation for that command. 

Besides the usual SCCS commands, several “pseudo-commands” can be issued. These are: 
edit Equivalent to “get -e”. 

delget Perform a delta on the named files and then get new versions. The new versions will 

have id keywords expanded, and will not be editable. The -m, -p, -r, -s, and -y flags 
will be passed to delta, and the -b, -c, -e, -i, -k, -1, -s, and -x flags will be passed to 
get 

deledit Equivalent to “delget” except that the “get” phase includes the “-e” flag. This 

option is useful for making a “checkpoint” of your current editing phase. The same 
flags will be passed to delta as described above, and all the flags listed for “get” 
above except -e and -k are passed to “edit”. 

create Creates an SCCS file, taking the initial contents from the file of the same name. Any 

flags to “admin” are accepted. If the creation is successful, the files are renamed 
with a comma on the front These should be removed when you are convinced that 
the SCCS files have been created successfully. 

fix Must be followed by a -r flag. This command essentially removes the named delta, 

but leaves you with a copy of the delta with the changes that were in it. It is useful 
for fixing small compile bugs, etc. Since it doesn’t leave audit trails, it should be 
used carefully. 

clean This routine removes everything from the current directory that can be recreated from 

SCCS files. It will not remove any files being edited. If the -b flag is given, 
branches are ignored in the detamination of whether they are being edited; this is 
dangm)us if you are keeping the branches in the same directory. 

unedit This is the opposite of an “edit” or a “get -e”. It should be used with extreme cau¬ 

tion, since any changes you made since the get will be irretrievably lost 

info Gives a listing of all files being edited. If the -b flag is given, branches (i.e., SID’s 

with two or fewer componrats) are ignored. If the -u flag is given (with an optional 
argumrat) then only files being edited by you (or the named user) are listed. 

check Like “info” except that nothing is pinted if nothing is being edited, and a non-zero 

exit status is returned if anything is being edited. The intent is to have this included 
in an “install” entry in a makefile to insure that everything is included into the SCCS 
file before a vision is installed. 

tell Gives a newline-separated list of the files being edited on the standard output Takes 

the -b and -u flags like “info” and “check”. 

diffs Gives a “diff ’ listing betwe«i the current version of the program(s) you have out for 
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editing and the versions in SCCS format The -r, -c, -i, -x, and -t flags are passed to 
get; the -1, -s, -e, -f, -h, and -b options are passed to diff. The -C flag is passed to 
dijfas -c. 

print This command prints out verbose information about the named files. 

The -r flag runs sees as the real user rather than as whatever effective user sees is “set user id” to. 
The -d flag gives a root directory for the SCCS files. The default is the current directory. The -p flag 
defines the pathname of the directory in which the SCCS files will be found; “SCCS” is the default. 
The -p flag differs from the -d flag in that the -d argument is prepended to the entire pathname and 
the -p argumrat is inserted before the final component of the pathname. Fot example, “sees -d/x -py 
get a/b” will convert to “get /x/a/y/s.b”. The intent here is to create aliases such as “alias syssccs 
sees -d/usr/src” which will be used as “syssccs get cmd/who.c”. Also, if the environment variable 
PROJECT is set, its value is used to determine the -d flag. If it begins with a slash, it is taken directly; 
otherwise, the home directory of a user of that name is examined for a subdirectory “sre” or “source”. 
If such a directory is found, it is used. 

C^tain commands (such as admin) cannot be run “set user id” by all users, since this would allow 
anyone to change the authorizations. These commands are always run as the real user. 

EXAMPLES 

To get a file for editing, edit it, and produce a new delta: 

sees get -e file.c 
ex file.c 
sees delta file.c 

To get a file from another directory: 

sees -p/usr/src/sccs/s. get cc.c 
or 


sees get /usr/src/sccs/s.cc.c 

To make a delta of a large numba of files in ti» current directory: 
sees delta *.c 

To get a list of files being edited that are not on branches: 
sees info -b 

To delta everything being edited by you: 
sees delta 'sees tell -u' 

In a makefile, to get source files from an SCCS file if it does not already exist: 

SRCS = <list of source files> 

$(SRCS): 

sees get $(REL) $@ 

SEE ALSO 

admin(SCCS), chghist(SCCS), comb(SCCS), delta(SCCS), get(SCCS), help(SCCS), prt(SCCS), 
rmdcl(SCCS), sccsdiff(SCCS), what(SCCS) 

Eric Allman, An Introduetion to the Souree Code Control System 

BUGS 

It should be able to take directory arguments on pseudocommands like the SCCS commands do. 
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NAME 

script - make typescript of terminal session 

SYNOPSIS 

script [ -a ] [ file ] 

DESCRIPTION 

Script makes a typescript of everything printed on your terminal. The typescript is written to file, or 
appended to file if the -a option is given. It can be sent to the line printer later with Ipr. If no file 
name is given, the typescript is saved in the file typescript. 

The script ends when the foiked shell exits. 

This program is useful when using a crt and a hard-copy record of the dialog is desired, as for a student 
handing in a program that was developed on a crt when hard-copy terminals are in short supply. 

EUNICE NOTES 

Because pseudo-terminal drivers are currently not implemented in EUNICE, script is run through a 
pipe. As a result, there is no job control access to the shell while script is active. 

BUGS 

Script places everything in the log file. This is not what the naive user expects. 
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NAME 

sed - stream editor 
SYNOPSIS 

sed [ -n ] [ -e script ] [ -f sfile ] [ file ] ... 

DESCRIPTION 

Sed copies the named files (standard input default) to the standard ouQ}ut, edited according to a script of 
commands. The option causes the script to be takra firom file ^le; these options accumulate. If 
thCTe is just one -e option and no -Ts, the flag -e may be omitt^. The -n option suppresses the 
default output 

A script consists of editing commands, one per line, of the following form: 

[address [, address] ] function [arguments] 

In normal operation sed cyclically copies a line of input into a pattern space (unless there is something 
left after a ‘D’ command), t^plies in sequence all commands whose addresses select that pattern space, 
and at the end of the script copies the pattern space to the standard output (except under -n) and deletes 
the pattern space. 

An address is either a decimal number that counts input lines cumulatively across files, a that 
addresses the last line of input, or a context address, ‘/regular expression/’, in the style of ed{\) 
modified thus: 

The escape sequence ‘Nn’ matches a newline embedded in the pattern space. 

A command line with no addresses selects every pattern space. 

A command line with one address selects et^h pattern space that matches the address. 

A command line with two addresses selects the inclusive range from the first pattern space that matches 
the first address through the next pattern space that matches the second. (If the second address is a 
number less than or equal to the line number first selected, only one line is selected.) Thereafter the 
process is repeated, looking again for the first address. 

Editing commands can be applied only to non-selected pattern spaces by use of the negation function 
*!’ (below). 

In the following list of functions the maximum number of permissible addresses for each function is 
indicated in parentheses. 

An argument denoted text consists of one or more lines, all but the last of which end with ‘V to hide 
the newline. Backslashes in text are treated like backslashes in the replacement string of an ‘s’ com¬ 
mand, and may be used to protect initial blanks and tabs against the snipping that is done on every 
script line. 

An argument denoted rfile or wfile must terminate the command line and must be preceded by exactly 
one blank. Each wfile is created before processing begins. There can be at most 10 distinct wfile argu¬ 
ments. 

(1) a\ 
text 

Apprad. Place text on the output before reading the next input line. 

(2) b label 

Branch to the ‘:’ command bearing the label. If label is empty, branch to the end of the 
script 

(2)c\ 

text 

Change. Delete the pattern space. With 0 or 1 address or at the end of a 2-address range, 
place text on the output Start the next cycle. 
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(2) d Delete the pattern space. Start the next cycle. 

(2)D Delete the initial segment of the pattern space through the first newline. Start the next cycle. 

(2) g Replace the contents of the pattern space by the contents of the hold space. 

(2) G Append the contents of the hold space to the pattern space. 

(2) h Replace the contents of the hold space by the contents of the pattern space. 

(2) H Append the contents of the pattern space to the hold space. 

(1) i\ 
text 

Insert. Place text on the standard output 

(2) n Copy the pattern space to the standard output Replace the pattern space with the next line of 

input 

(2)N Append the next line of input to the pattern space with an embedded newline. (The current 
line number changes.) 

(2)p Print Copy the pattern space to the standard output 

(2) P Copy the initial segment of the pattern spjKie through the first newline to the standard ouq)ut. 

(1) q Quit Branch to the end of the script Do not start a new cycle. 

(2) Trfile 

Read the contents of rfile. Place them on the ouq)ut before reading the next input line. 

(2) sfregular expressionireplacementifiags 

Substitute the replacement string for instances of the regular expression in the pattern space. 
Any character may be used instead of 7’. For a fuller description see ed{l). Flags is zero or 
more of 

g Global. Substitute for all nonoverlapping instances of the regular expression rather 
than just the first one. 

p Print the pattern space if a replacement was made, 
w wfile Write. Append the patt^ space to wfile if a replacement was made. 

(2) t label 

Test Branch to the command bearing the label if any substitutions have been made since 
the most recent reading of an input line or execution of a ‘t’. If label is empty, branch to the 
end of the script 

(2) w wfile 

Write. Append the pattern space to wfile. 

(2)x Exchange the contents of the pattern and hold spaces. 

(2) yistringllstringll 

Transform. Replace all occurrences of characters in stringl with the corresponding character 
in stringl. The lengths of stringl and stringl must be equal. 

(2)! function 

Don’t Apply the function (or group, if function is ‘{’) only to lines not selected by the 
addressees). 

(0): label 

This command does nothing; it bears a label for ‘b’ and ‘t’ commands to branch to. 

(1) = Place the current line number on the standard output as a line. 

(2) { Execute the following commands through a matching *}’ only when the pattern space is 
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selected. 

(0) An empty command is ignored. 
SEE ALSO 

ed(l), grep(l), awk(l), lex(l) 
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NAME 

sendbug - mail a system bug report to 4bsd-bugs 

SYNOPSIS 

sendbug [ address ] 

DESCRIPTION 

Bug reports sent to ‘4bsd-bugs@Beikeley£DU’ are intercepted by a program which expects bug reports 
to conform to a standard format Sendbug is a shell script to help the user compose and mail bug 
reports in the correct format Sendbug works by invoking the editor specified by the environment vari¬ 
able EDITOR on a temporary copy of the bug report format outline. The user must fill in the appropri¬ 
ate fields and exit the editor. The default editor is vi(l). Sendbug then mails the completed report to 
‘4bsd-bugs@ Berkeley£DU’ or the address specified on the command line. 

FILES 

/usr/ucb/bugformat contains the bug report outline 
SEE ALSO 

vi(l), environ(7), sendmail(8) 
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NAME 

sh, for, case, if, while, :,., break, continue, cd, eval, exec, exit, export, login, read, readonly, set, shift, 
times, trap, umask, wait - command language 

SYNOPSIS 

sh [ -eeiknrstuvx ] [ arg ] ... 

DESCRIPTION 

Sh is a command programming language that ex«:utes commands read from a terminal or a file. See 
invocation for the meaning of arguments to the shell. 

Commands. 

A simple-command is a sequence of non blank words separated by blanks (a blank is a tab or a space). 
The first word specifies the name of the command to be executed. Except as specified below the 
remaining words are passed as arguments to the invoked command. The command name is passed as 
argument 0 (see execve(2)). The value of a simple-command is its exit status if it terminates normally 
or 200+status if it terminates abnormally (see sigvec(2) for a list of status values). 

A pipeline is a sequence of one or more commands separated by |. The standard ouq)ut of each com¬ 
mand but the last is connected by a pipe (2) to the standard input of the next command. Each command 
is run as a sq)arate process; the shell waits for the last command to terminate. 

A list is a. sequence of one or more pipelines separated by ;, &, && or 11 and optionally terminated by 
; or &. ; and & have equal precedence which is lower than that of && and 11, && and 11 also have 
equal precedence. A semicolon causes sequential execution; an ampersand causes the preceding pipe¬ 
line to be executed without waiting for it to finish. The symbol && (| |) causes the list following to be 
executed only if the preceding pipeline returns a zero (non zero) value. Newlines may appear in a list, 
instead of semicolons, to delimit commands. 

A command is either a simple-command or one of the following. The value returned by a command is 
that of the last simple-command executed in the command. 

for name [in word ...] do list done 

Each time a for command is executed name is set to the next word in the for word list If 
in word ... is omitted, in "$@" is assumed. Execution ends when there are no more words in 
the list 

case word in [pattern [ | pattern ] ...) list ;;]... esac 

A case command executes the list associated with the first pattern that matches word. The form 
of the patterns is the same as that used for file name generation. 

if list then list [elif list then list] ... [else list] fi 

The list following if is executed and if it returns zero the list following then is executed. Oth¬ 
erwise, the list following elif is executed and if its value is zero the list following then is exe¬ 
cuted. Failing that the else list is executed. 

while list [do list] done 

A while command repeatedly executes the while list and if its value is zero executes the do 
list; otherwise the loop tominates. The value returned by a while command is that of the last 
executed command in the do Ust. until may be used in place of while to negate the loop termi¬ 
nation test 

( list) Execute list in a subshell. 

( list ) list is simply executed. 

The following words are only recognized as the first word of a command and when not quoted, 
if then else elif fi case in esac for whfle until do done { ) 
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Command substitution. 

The standard output from a command enclosed in a pair of back quotes C') may be used as part or all 
of a word; trailing newlines are removed. 

Parameter substitution. 

The character $ is used to introduce substitutable parameters. Positional parameters may be assigned 
values by set. Variables may be set by writing 

name=value [ name=value ] ... 

$ [parameter } 

A parameter is a sequence of letters, digits or underscores (a name), a digit, or any of the 
characters ♦ @ # ? - $ !. The value, if any, of the parameter is substituted. The braces are 
required only when parameter is followed by a letter, digit, (x* underscore that is not to be 
interpreted as part of its name. If parameter is a digit, it is a positional parameter. If parame¬ 
ter is * or @ then all the positional parameters, starting with $1, are substituted separated by 
spaces. $0 is set from argument zero when the shell is invoked. 

$ [parameter-word ) 

If parameter is set, substitute its value; otherwise substitute word. 

$ [parameter= word ) 

If parameter is not set, set it to word: the value of the parameter is then substituted. Positional 
parameters may not be assigned to in this way. 

$ [parameter ? word ] 

If parameter is set, substitute its value; oth^^ise, print word and exit from the shell. If word 
is omitted, a standard message is printed. 

$ [parameter+word ) 

If parameter is set, substitute word; otherwise substitute nothing. 

In the above word is not evaluated unless it is to be used as the substituted string. (So that, for exam¬ 
ple, echo ${d-'pwd'} will only execute pwd if is unset.) 

The following parameters are automatically set by the shell. 

# The number of positional parameters in decimal. 

- Options supplied to the shell on invocation or by set. 

? The value returned by the last executed command in decimal. 

$ The process number of this shell. 

! The process number of the last background command invoked. 

The following parameters are used but not set by the shell. 

HOME The default argument (home directory) for the cd command. 

PATH The search path for commands (see execution). 

MAIL If this variable is set to the name of a mail file, the shell informs the user of the 
arrival of mail in the specified file. 

PSl Primary ixompt string, by default ’$ ’. 

PS2 Secondary prompt string, by default ’> ’. 

IPS Internal field separators, normally space, tab, and newline. IFS is ignored if sh is 
running as root or if the effective user id differs firom the real usct id. 

Blank interpretation. 

After parameter and command substitution, any results of substitution are scanned for internal field 
separator characters (those found in $IFS) and split into distinct arguments where such characters are 
found. Explicit null arguments ("" or ") are retained. Implicit null arguments (those resulting from 
parameters that have no values) are removed. 
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File name generation. 

Following substitution, each command word is scanned for the characters ♦, ? and [. If one of these 
characters appears, the word is regarded as a pattern. The word is replaced with alphabetically sorted 
file names that match the pattmi. If no file name is found that matches the pattern, the word is left 
unchanged. The character . at the start of a file name or immediately following a /, and the character /, 
must be matched explicitly. 

* Matches any string, including the null string. 

? Matches any single character. 

[... ] Matches any one of the characters enclosed. A pair of charact^ separated by - matches any 
character lexically betwera the pair. 

Quoting. 

The following characters have a special meaning to the shell and cause termination of a word unless 
quoted. 

;&()!<> newline space tab 

A character may be quoted by preceding it with a \. Nnewline is ignored. AU charactos enclosed 
between a pair of quote marks ("). except a single quote, are quoted. Inside double quotes ("") 
parameter and command substitution occurs and \ quotes the characters \ ' " and $. 

"$♦" is equivalent to "$1 $2whereas 
is equivalent to "$1" "$2" «.. 

Prompting. 

When used interactively, the shell prompts with the value of PSl before reading a command. If at any 
time a newline is typed and further input is needed to complete a command, the secondary prompt 
($PS2) is issued. 

Input output. 

Before a command is executed its input and output may be redirected using a special notation inter¬ 
preted by the shell. The following may appear anywhere in a simple-command or may precede or fol¬ 
low a command and are not passed on to the invoked command. Substitution occurs before word or 
digit is used. 

< word Use file word as standard input (file de^riptor 0). 

> word Use file word as standard output (file descriptor 1). If the file does not exist, it is created; oth¬ 
erwise it is truncated to zero lengA. 

» word Use file word as standard ouq)ut If the file exists, output is appended (by seeking to the end); 
otherwise the file is created. 

« word The shell input is read up to a line the same as word, or end of file. The resulting document 
becomes the standard input If any character of word is quoted, no interpretation is placed 
upon the characters of the document; otherwise, parameter and command substitution occurs, 
Nnewline is ignored, and \ is used to quote the characters \ $ ' and the first character of word. 

<Sl digit 

The standard input is duplicated firom file descriptor dig^t; see dup(2). Similarly for the stan¬ 
dard ouq)ut using >. 

< & - The standard input is closed. Similarly for the standard output using >. 

If one of the above is preceded by a digit, the file descriptor created is that specified by the digit 
(instead of the default 0 or 1). For example, 

... 2>&1 

creates file descriptor 2 to be a duplicate of file descriptor 1. 
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If a command is followed by & then the default standard input for the command is the empty file 
(/dev/nuU). Otherwise, the environment for the execution of a command contains the file descriptors of 
the invoking shell as modified by input output specifications. 

Environment. 

The environment is a list of name-value pairs that is passed to an executed program in the same way as 
a normal argument list; see execve(2) and environ(J). The shell interacts with the environment in 
several ways. On invocaticm, the shell scans the environment and creates a parameter for each name 
found, giving it the corresponding value. Executed commands inherit the same environment If the 
user modifies the values of these parameters or creates new ones, none of these affects the environment 
unless the export command is used to bind the shell’s parameter to the environment The environment 
seen by any executed command is thus composed of any unmodified name-value pairs originally inher¬ 
ited by the shell, plus any modifications or additions, aU of which must be noted in export commands. 

The environment for any simple-command may be augmented by prefixing it with one or more assign¬ 
ments to parameters. Thus these two lines are equivalent 

TERM=450 cmd args 

(export TERM; TERM=450; cmd args) 

If the -k flag is set ail keyword arguments are placed in the environment, even if the occur after the 

command name. The following prints ’a=b c’ and ’c’: 

echo a=b c 

set -k 

echo a=b c 

Signals. 

The INTERRUPT and QUIT signals for an invoked command are ignored if the command is followed 
by &; otherwise signals have the values inherited by the shell from its parent (But see also trap.) 

Execution. 

Each time a command is executed the above substitutions are carried out Except for the ’special com¬ 
mands’ listed below a new process is created and an attempt is made to execute the command via an 
execveO). 

The shell parameter $PATH defines the search path for the directory containing the command. Each 
alternative directory name is separated by a colon (:). The default path is :/bin:/usr/bin. If the com¬ 
mand name contains a /, the search path is not used. Otherwise, each directcxy in the path is searched 
for an executable file. If the file has execute permission but is not an a.out file, it is assumed to be a 
file containing shell commands. A subshell (i.e., a separate process) is spawned to read it. A 
parenthesized command is also executed in a subshell. 

Special commands. 

The following commands are executed in the shell process and except where specified no input output 
redirection is permitted for such commands. 

# For non-interactive shells, everything following the # is treated as a comment, i.e. the rest of 
the line is ignored. For interactive shells, the # has no special effect 

: No effect; the command does nothing. 

,file Read and execute commands from file and return. The search path $PATH is used to find the 
directory containing file. 
break [n] 

Exit from the enclosing for or while loop, if any. If n is specified, break n levels, 
continue [n] 

Resume the next iteration of the enclosing for or while loop. If n is specified, resume at the 
n-th enclosing loop, 
cd [arg] 

Change the current directory to arg. The shell parameter $HOME is the default arg. 



SH(1) 


UNIX Programmer’s Manual 


SH(1) 


eval [arg ...] 

The arguments are read as input to the shell and the resulting command(s) executed, 
exec [ arg ... ] 

The command specified by the arguments is executed in place of this shell without creating a 
new process. Input output arguments may appear and if no other arguments are given cause 
the shell input output to be modified. 

exit [n] 

Causes a non interactive shell to exit with the exit status specified by n. If n is omitted, the 
exit status is that of the last command executed. (An end of file will also exit from the shell.) 
export [name ...] 

The given names are marked for automatic export to the environment of subsequentiy-executed 
commands. If no arguments are given, a list of exportable names is printed, 
login [arg ...] 

Equivalent to ’exec login arg ...’. 
read name ... 

One line is read from the standard input; successive words of the input are assigned to the vari¬ 
ables name in order, with leftover words to the last variable. The return code is 0 unless the 
end-of-file is encountered, 
readonly [name ...] 

The given names are marked readonly and the values of the these names may not be changed 
by subsequent assignment If no arguments are given, a list of all readonly names is printed, 
set [-eknptuvx [ arg ... ] ] 

-e If non interactive, exit immediately if a command fails. 

-k All keyword arguments are placed in the environment for a command, not just those 
that precede the command name. 
oQ Read commands but do not execute them. 

-t Exit after reading and executing one command. 

-u Treat unset varis^les as an error when substituting. 

-v Print shell input lines as they are read. 

-X Print commands and their arguments as they are executed. 

- Turn off the -x and -v options. 

These flags can also be used upon invocation of the shell. The current set of flags may be 
found in $-. 

Remaining arguments are positional parameters and are assigned, in order, to $1, $2, etc. If no 
arguments are given, the values of all names are printed. 

shift The positional parameters from $2... are renamed $1... 

times Print the accumulated usct and system times for processes run from the shell. 

trap [arg] [n] ... 

Arg is a command to be read and executed when the shell receives signal(s) n. (Note that arg 
is scanned once when the trap is set and once when the trap is taken.) Trap commands are exe¬ 
cuted in order of signal number. If arg is absent, all trap(s) n are reset to their original values. 
If arg is the null string, this signal is ignored by the shell and by invoked commands. If n is 
0, the command arg is executed on exit from the shell, otherwise upon receipt of signal n as 
numbered in sigvec(2). Trap with no arguments prints a list of commands associated with 
each signal number. 

umask [ nnn ] 

The usw file creation mask is set to the octal value nnn (see umask(2y). If nnn is omitted, the 
current value of the mask is printed. 

wait [n] 

Wait for the specified process and i:qx)rt its lamination status. If n is not given, all currently 


April 24, 1989 


The Wollongong Group 


5 



SH(1) 


UNIX Programmer’s Manual 


SH(1) 


active child processes are waited for. The return code from this command is that of the pro¬ 
cess waited for. 

Invocation. 

If the first characto: of argument zero is commands are read from $home/. profile, if such a file 
exists. Commands are then read as described below. The following flags are interpreted by the shell 
when it is invoked. 

-c string If the >c flag is present, commands are read from string. 

-s If the -s flag is present or if no arguments remain then commands are read from the stan¬ 

dard input Shell output is written to file descriptor 2. 

-i If the -4 flag is present or if the shell input and output are attached to a terminal (as told 

by gtty) then this shell is interactive. In this case the terminate signal SIGTERM (see 
sigvec(2)) is ignored (so that ’kill 0’ does not kill an interactive shell) and the interrupt 
signal SIGINT is caught and ignored (so that wait is interruptible). In all cases SIGQUIT 
is ignored by the shell. 

The remaining flags and arguments are described under the set command. 

FILES 

SHOME/. profile 
/tmp/sh* 

/dev/null 

SEE ALSO 

csh(l), test(l), execve(2), environ(7) 

DIAGNOSTICS 

Errors detected by the shell, such as syntax errors cause the shell to return a non zero exit status. If the 
shell is being used non interactively then execution of the shell file is abandoned. Otherwise, the shell 
returns the exit status of the last command executed (see also exit). 

BUGS 

If « is used to provide standard input to an asynchronous process invoked by &, the shell gets mixed 
up about naming the input document A garbage file /tmp/sh’^ is created, and the shell complains about 
not being able to find the file by another name. 
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NAME 

size - size of an object file 

SYNOPSIS 

size [ object... ] 

DESCRIPTION 

Size prints the (decimal) number of bytes required by the text, data, and bss portions, and their sum in 
hex and decimal, of each object-file argument If no file is specified, a.out is used. 

SEE ALSO 

a.out(5) 
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NAME 

sleep - suspend execution for an interval 

SYNOPSIS 

sleep time 

DESCRIPTION 

Sleep suspends execution for time seconds. It is used to execute a command after a certain amount of 
time as in: 

(sleep 105; command)& 
or to execute a command every so often, as in: 

while true 
do 

command 
sleep 37 

done 


SEE ALSO 

setitimer(2), alarm(3C), sleep(3) 

BUGS 

Time must be less than 2,147,483,647 seconds. 
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NAME 

soelim - eliminate .so’s from nroff input 

SYNOPSIS 

soelim [ file ... ] 

DESCRIPTION 

Soelim reads the specified files or the standard input and performs the textual inclusion implied by the 
nroff directives of the form 

.so somefile 

when they aiq)ear at the beginning of input lines. This is useful since programs such as tbl do not nor¬ 
mally do this; it allows the placement of individual tables in separate files to be run as a part of a large 
document 

An argument consisting of a single minus (-) is taken to be a file name corresponding to the standard 
input 

Note that inclusion can be suppressed by using instead of i.e. 

'so /usr/lib/tmac.s 

A sample usage of soelim would be 

soelim exum?.n I tbl I nroff -ms I col I Ipr 

SEE ALSO 

colcit(l), more(l) 

BUGS 

The format of the source commands must involve no strangeness - exactly one blank must precede and 
no blanks follow the file name. 
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NAME 

sort - sort or merge files 
SYNOPSIS 

sort [ -mubdfinrtx ] [ -^posl [ -pos2 ] ] ... [ -o name ] [ -T directory ] [ name ] ... 

DESCRIPTION 

Sort sorts lines of all the named files together and writes the result on the standard output. The name 
means the standard input. If no input files are named, the standard input is sorted. 

The default sort key is an entire line. Default ordering is lexicographic by bytes in machine collating 
sequence. The ordering is affected globally by the following options, one or more of which may 
appear. 

b Ignore leading blanks (spaces and tabs) in field comparisons, 
d ‘Dictionary’ order: only letters, digits and blanks are significant in comparisons, 
f Fold upper case letters onto lower case. 

i Ignore characters outside the ASCII range 040-0176 in nonnumeric comparisons. 

n An initial numeric string, consisting of optional blanks, optional minus sign, and zero or more 

digits with optional decimal point, is sorted by arithmetic value. Option n implies option b. 

r Reverse the sense of comparisons. 

tx Tab character’ separating fields is x. 

The notation -k-posl -pos2 restricts a sort key to a field beginning at posl and ending just before pos2. 
Posl and pos2 each have the form m.n, optionally followed by one or more of the flags bdfinr, where 
m tells a number of fields to skip from the beginning of the line and n tells a number of characters to 
skip further. If any flags are present they override all the global ordering options for this key. If the b 
option is in effect n is counted firom the first nonblank in the field; b is attached independently to pos2. 
A missing ji means .0; a missing -pos2 means the end of the line. Under the -tc option, fields are 
strings separated by x; otherwise fields are nonempty nonblank strings separated by blanks. 

When there are multiple sort keys, later keys are compared only after all earlier keys compare equal. 
Lines that otherwise compare equal are ordered with all bytes significant. 

These option arguments are also understood; 

c Check that the input file is sorted according to the ordering rules; give no output unless the file is 
out of sort. 

m Merge only, the input files are already sorted. 

o The next argument is the name of an output file to use instead of the standard output This file 
may be the same as one of the inputs. 

T The next argument is the name of a directory in which temporary files should be made. 

u Suppress all but one in each set of equal lines. Ignored bytes and bytes outside keys do not parti¬ 
cipate in this comparison. 

EXAMPLES 

Print in alphabetical order all the unique spellings in a list of words. Capitalized words differ from 
uncapitalized. 

sort -u +0f +0 list 

Print the password file (passwd(5)) sorted by user id number (the 3rd colon-separated field), 
sort -t +2n /etc^asswd 
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Print the first instance of each month in an already sorted file of (month day) entries. The options -um 
with just one input file make the choice of a unique representative from a set of equal lines predictable. 

sort -um +0 -1 dates 

FILES 

/usr/tmp/stm*, /tmp/* first and second tries for temporary files 
SEE ALSO 

uniq(l), comm(l), rev(l), join(l) 

DIAGNOSTICS 

Comments and exits with nonzero status for various trouble conditions and for disorder discovered 
under option -c. 

BUGS 

Very long lines are silently truncated. 
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NAME 

sortbib - sort bibliographic database 
SYNOPSIS 

sortbib [ -sKEYS ] database ... 

DESCRIPTION 

Sortbib sorts files of records containing r^er key-letters by user-specified keys. Records may be 
separated by blank lines, or by .[ and .] delimiters, but the two styles may not be mixed together. This 
program reads through each database and pulls out key fields, which are sorted separately. The sorted 
key fields contain the file pointer, byte offset, and length of corresponding records. These records are 
delivered using disk seeks and reads, so sortbib may not be used in a pipeline to read standard input. 

By default, sortbib alphabetizes by the first %A and the %D fields, which contain the senior author and 
date. The -s option is used to specify new KEYS. For instance, -sATD will sort by author, title, and 
date, while -sA+D will sort by all authors, and date. Sort keys past the fourth are not meaningful. No 
more than 16 databases may be sorted together at one time. Records longer than 4096 characters will 
be truncated. 

Sortbib sorts on the last word on the %A line, which is assumed to be the author’s last name. A word 
in the final positicMi, such as “jr.” or “ed.”, will be ignored if the name beforehand ends with a 
comma. Authors with two-word last names or unusual constructions can be sorted correctly by using 
the convention “NO” in place of a blank. A %Q field is considered to be the same as %A, except 
sorting begins with the first, not the last, word. Sortbib sorts on the last word of the %D line, usually 
the year. It also ignores leading articles (like “A” or “The”) when sorting by titles in the %T or %J 
fields; it will ignore articles of any modem European language. If a sort-significant field is absent from 
a record, sortbib places that record before other records containing that field. 

SEE ALSO 

refer(l), addbib(l), roffbib(l), indxbib(l), lookbib(l) 

AUTHORS 

Greg Shenaut, Bill Tuthill 

BUGS 

Records with missing author fields should probably be sorted by title. 
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NAME 

spell, spellin, spellout - find spelling errors 
SYNOPSIS 

spell [ -V ] [ -b ] [ -X ] [ -d hlist ] [ -s hstop ] [ -h spellhist ] [ file ] ... 
spellin [ list ] 
spellout [ -d ] list 
DESCRIPTION 

Spell collects words frOTi the named documents, and looks them up in a spelling list. Words that nei¬ 
ther occur among nor are derivable (by applying certain inflections, prefixes or suffixes) from words in 
the spelling list are printed on the standard output If no files are named, words are collected from the 
standard input 

Spell ignores most troff, tbl and eqn{\) constructions. 

Under the -v option, all words not literally in the spelling list are printed, and plausible derivations 
from spelling list words are indicated. 

Under the -b option, British spelling is checked. Besides preferring centre, colour, speciality, travelled, 
etc., this option insists upon -ise in words like standardise, Fowler and the OED to the contrary not¬ 
withstanding. 

Under the -x option, every plausible stem is printed with ‘=* for each word. 

The spelling list is based on many sources. While it is more haphazard than an ordinary dictionary, it 
is also more effective with proper names and popular technical words. Coverage of the specialized 
vocabularies of biology, medicine and chemistry is light 

The auxiliary files used for the spelling list stop list and history file may be specified by arguments 
following the -d, -s, and -h options. The default files are indicated below. Copies of all output may 
be accumulated in the history file. The stop list filters out misspellings (e.g. thier=thy-y+ier) that would 
otherwise pass. 

Two routines help maintain the hash lists used by spell. Both expect a set of words, one per line, from 
the standard input Spellin combines the words tom the standard input and the preexisting list file and 
places a new list on the standard output If no list file is specified, the new list is created tom scratch. 
Spellout looks up each word from the standard input and prints on the standard output those that are 
missing tom (or present on, with option -d) the hashed list file. For example, to verify that hookey is 
not on the default spelling list add it to your own private list and then use it with spell, 

echo hookey I spellout /usr/dict/hlista 

echo hookey I spellin /usr/dict/hlista > myhlist 

spell -d myhlist huckfinn 

FILES 

/usr/dict/hlist[ab] hashed spelling lists, American & British, default for -d 

/usr/dict/hstop hashed stop list default for -s 

/dev/null history file, default for -h 

/tmp/spell.SS* temporary files 

/usr/liWspell 

SEE ALSO 

deroff(l), sort(l), tee(l), sed(l) 

EUNICE NOTES 

As spell(l) uses pipes, the VMS quota ‘BYTLM’ should be set to at lease 30,(XX). Reference the VMS 
utility manual for AUTHORIZE. 
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BUGS 

The spelling list’s coverage is uneven; new installations will probably wish to monitor the output for 
several months to gather local additions. 

British spelling was done by an American. 
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NAME 

Spline - interpolate smooth curve 

SYNOPSIS 

spline [ option ] ... 

DESCRIPTION 

Spline takes pairs of numbers from the standard input as abcissas and ordinates of a function. It pro¬ 
duces a similar set, which is £q}proximateIy equally spaced and includes the input set, on the standard 
output The cubic spline output (R. W. Hamming, Numerical Methods for Scientists and Engineers, 
2nd ed., 349ff) has two continuous derivatives, and sufficiendy many points to look smooth when plot¬ 
ted, for example by graph{\Q). 

The following options are recognized, each as a separate argument 

-a Supply abscissas automatically (they are missing from the input); spacing is given by the next 
argument, or is assumed to be 1 if next argument is not a number. 

-k The constant k used in the boundary value computation 

>0 = ky'i. Yn = ky'n-i 

is set by the next argument By default k = 0. 

-n Space output points so that approximately n intervals occur between the lower and upper x limits. 
(Default n = 100.) 

-p Make output periodic, i.e. match derivatives at ends. First and last input values should normally 
agree. 

-X Next 1 (or 2) arguments are lower (and upper) x limits. Normally these limits are calculated 
from the data. Automatic abcissas start at lower limit (default 0). 

SEE ALSO 

graph(lG), plot(lG) 

DIAGNOSTICS 

When data is not stricdy monotone in x. spline reproduces the input without interpolating extra points. 

BUGS 

A limit of 1000 input points is enforced silently. 
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NAME 

split - split a file into pieces 
SYNOPSIS 

split [ -n ] [ file [ name ] ] 

DESCRIPTION 

Split reads file and writes it in n-line pieces (default KXX)), as many as necessary, onto a set of output 
files. The name of the first output file is name with aa appended, and so on lexicographically. If no 
output name is given, x is default 

If no input file is given, or if - is given in its stead, then the standard input file is used. 
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NAME 

strings - find the printable strings in a object, or other binary, file 
SYNOPSIS 

strings [ - ] [ -o ] [ -number ] file ... 

DESCRIPTION 

Strings looks for ascii strings in a binary file. A string is any sequence of 4 or more printing characters 
ending with a newline or a null. Unless the - flag is given, strings only looks in the initialized 
space of object files. If the -o flag is given, then each string is preced^ by its offset in the file (in 
octal). If the -number flag is given then number is used as the minimum string length rather than 4. 

Strings is useful for identifying random object files and many other things. 

SEE ALSO 

Odd) 

BUGS 

The algorithm for identifying strings is extremely primitive. 
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NAME 

strip - remove symbols and relocation bits 

SYNOPSIS 

strip name ... 

DESCRIPTION 

Strip removes the symbol table and relocation bits ordinarily attached to the output of the assembler 
and loader. This is useful to save space after a program has been debugged. 

The effect of strip is the same as use of the -s option of Id. 

FILES 

/tmp/stm? temporary file 

SEE ALSO 
ld(l) 
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NAME 

Struct - structure Fortran programs 
SYNOPSIS 

struct [ option ] ... file 
DESCRIPTION 

Struct translates the Fmtran program specified by file (standard input default) into a Ratfor program. 
Wherever possible, Ratfor control constructs repla^ the original Fortran. Statement numbers appear 
only where still mcessary. Cosmetic changes are made, including changing Hollerith strings into 
quoted strings and relational operators into symbols (.e.g. ".GT." into ">"). The output is appropriately 
indented. 

The following (^tions may occur in any order. 

-s Input is accepted in standard format, i.e. comments are specified by a c, C, or * in column 1, 
and continuation lines are specified by a nonzero, nonblank character in column 6. Normally 
input is in the form accepted by/77(l) 

-i Do not turn computed goto stat^ents inu> switches. (Ratfor does not turn switches back into 
computed goto statements.) 

-a Turn sequences of else ifs into a non-Ratfor switch of the form 
switch 

( case predl: code 
case pied2: code 
case pred3: code 
default: code 

} 

The case predicates are tested in order, the code t ypr o pr iate to only one case is executed. This 
generalized form of switch statement does not occur in Ratfor. 

-b Generate goto’s instead of multilevel break statements. 

-n Generate goto’s instead of multilevel next statements. 

-tn Make the nonzero integer n the lowest valued label in the output program (default 10). 

-cn Increment successive labels in the ouQjut program by the nonzero integer n (default 1). 

-en If n is 0 (default), place code within a loop only if it can lead to an iteration of the loop. If n 

is nonzox), admit a small code segments to a loop if otherwise the loop would have exits to 
several places including the segment, and the segment can be reached only from the loop. 
‘Small’ is close to, but not equal to, the number of statements in the code segment Values of 
n under 10 are suggested. 

FILES 

/tmp/struct* 

/usr/lib/struct/» 

SEE ALSO 

07(1) 

BUGS 

Struct knows Fortran 66 syntax, but not full Fortran 77. 

If an input FOTtran program contains identifiers which are reserved words in Ratfor, the structured ver¬ 
sion of the program will not be a valid Ratfor program. 

The labels generated cannot go above 32767. 

If you get a goto without a target, try -e . 


April 24, 1989 


The Wollongong Group 


1 



STTY(l) 


UNIX Programmer’s Manual 


STrY(l) 



stty - set terminal options 

SYNOPSIS 

Stty [ option ... ] 

DESCRIPTION 

Stty sets certain I/O options on the current output terminal, placing its output on the diagnostic output 
With no argument, it reports the speed of tte tmninal and the settings of the options which are 
different from their defaults. Use of one of the following options modifies the output as described: 

all All ncnmally used option settings are reported. 

everything Everything stty knows about is printed. 

speed The terminal speed alone is printed on the standard output 

size The terminal (window) sizes are printed on the standard output first rows and then 
columns. 



The option strings are selected from the following set: 

even allow even parity input 

-even disallow even parity input 

odd allow odd parity input 

-odd disallow odd parity input 

raw raw mode input (no input processing (erase, kill, interrupt...); parity bit passed back) 

-raw negate raw mode 

cooked same as ’-raw’ 

cbreak make each characto* available to readiZ) as received; no erase and kill processing, but all 
other processing (interrupt suspend,...) is performed 
-cbreak make characters available to read only when newline is received 

-nl allow carriage return for new-line, and output CR-LF for carriage return or new-line 

nl accept only new-line to end lines 

echo echo back every character typed 

-echo do not echo characters 

lease map uppo* case to lower case 

-lease do not map case 

tandem enable flow control, so that the system srads out the stop character when its internal queue 
is in danger of overflowing on input, and sends the start character when it is ready to accept 
further input 

-tandem disable flow control 

-tabs replace tabs by spaces when printing 

tabs preserve tabs 

ek set oxise and kill characters to # and @ 

For the following commands which take a character argument c, you may also specify c as the “u” or 
“undef’, to set the value to be undefined. A value of *“*x”, a 2 character sequence, is also interpreted 
as a control character, with representing delete. 

erase c set erase character to c (default *#*, but often reset to “H.) 

kill c set kill character to c (default but often reset to *U.) 

intr c set interrupt character to c (default DEL or *? (delete), but often reset to 'C.) 

quit c set quit character to c (default control \) 

start c set start character to c (default control Q.) 

stop c set stop character to c (default control S.) 

eof c set end of file character to c (default control D.) 

brk c set break character to c (default undefined.) This character is an additional character causing 
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wakeup. 
crO crl cr2 cr3 

select style of delay for carriage return (see ioctl(2)) 
nlO nil 1112 nl3 

select style of delay for linefeed 
tabO tabl tab2 tab3 

select style of delay for tab 
ffO ffl select style of delay for form feed 

bsO bsl select style of delay for backspace 

tty33 set all modes suitable for die Teletype Corporation Model 33 terminal. 

tty37 set all modes suitable fcv the Teletype Corporation Model 37 tominal. 

vM5 set all modes suitable for Digital Equipment Corp. VT05 terminal 

dec set all modes suitable for Digital ^uipment Corp. op^ting syst^s users; (erase, kill, and 

interrupt characters to "?, *U, and X, deccdq and “newcrt**.) 

tn300 set all modes suitable for a Genoal Electric TermiNet 300 

ti700 set all modes suitable for Texas Instruments 700 series terminal 

tek set all modes suitable for Tektronix 4014 terminal 

0 hang up phone line immediately 

50 75 110 134 150 200 300 600 1200 1800 2400 4800 9600 exta extb 

Set terminal baud rate to the numb^ given, if possible. (These are the speeds supported by 
the DH-11 interface). 

rows n The terminal size is recorded as having n rows, 

columns n The terminal size is recorded as having n columns, 
cols n is an alias for columns. 

A teletype driver which supports the job control processing of cj/t(l) and more fimctionality than the 
basic driver is fully describe in Tt» following options apply only to it 

new Use new driver (switching flushes typeahead). 

crt Set options for a CRT (crtbs, ctlecho and, if >= 1200 baud, crterase and crfldll.) 

crtbs Echo backspaces on erase charact^. 

prterase For printing terminal echo a:ased charact^ backwards within and *7”. 
crterase Wipe out oased charact^ with **b^kspace-space-backspace." 

-crterase Leave erased characters visible; just backspace, 
crtkill Wipe out input oa like kill ala crterase. 

-crtkill Just echo line kill characto: and a newline (xi line kill. 

ctlecho Echo control characters as “"x" (and delete as “'7”.) Print two backspaces following the 

EOT charactOT (control D). 

-ctlecho Control characters echo as themselves; in cooked mode EOT (control-D) is not echoed. 

decctlq After output is suspended (normally by "S), only a start character (normally "Q) will restart 
it This is compatible with DEC’S vendor supplied systems. 

-decctlq After output is suspended, any character ^rped will restart it; the start character will restart 
output without providing any input (This is the default) 
tostop Background jobs stc^ if they attempt t^minal output. 

-tostop Output from background jobs to the terminal is allowed, 
tilde Convert to on output (for Hazeltine terminals). 

-tilde Leave poor alone. 

flusho Ouq}ut is being discarded usually because user hit control O (internal state bit). 

-flusho Ouq}ut is not being discarded. 

pendin Input is pending after a switch from cbreak to cooked and will be re-input when a read 
becomes pending or more input arrives (intranal state bit). 
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-pendin 

pass8 

-pass8 

mdmbuf 

-flidmbuf 

litout 

^tout 

nohang 

-4ioliang 

etxack 


Input is not pending. 

Passes all 8 bits through (m input, in any mode. 

Strips the 0200 bit on input except in raw mode. 

Sta^stop output on carrier transitions (not implemented). 

Return error if write attempted after cairi^ drops. 

Send output characters without any inocessing. 

Do normal ouq)ut processing, insoling delays, etc. 

Don’t srad hangup signal if carrier drops. 

Send hangiQ) signal to control i»ocess group when carrier drops. 
Diablo style etx/ack handshaking (not implemented). 


The following special characters are applicable only to the new teletype driver and are not normally 
changed. 

SUSP c set suspend process character to c (default control Z). 

dsusp c set delayed suspend process charact^ to c (default control Y). 

rpmt c set reprint line character to c (default control R). 

flush c set flush ouq)ut characto’ to c (default control O). 
werase c set word erase character to c (default control W). 

Inext c set literal next charact^ to c (default ccmtrol V). 


EUNICE NOTES 

Since the VMS tonminal driver is used by EUNICE, the re-settable terminal attributes are limited to 
raw, echo and tabs. 

Stty cbreak does not work in EUNICE. When the shell forks a child process to set the cbreak flag and 
then exits the cbreak flag is not set for the parent process (i.e., the shell). Stty(l) raw works because it 
directly changes the VMS terminal mode to PASSALL. 

However, it should be noted that ioctl(2) correctly sets the cbreak flag within user programs. Users 
should set terminal modes within programs using ioctl(2). 


SEE ALSO 

ioctl(2), tabs(l), tset(l), tty(4) 
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NAME 

Style - analyze surface characteristics of a document 
SYNOPSIS 

Style [ -jnl ] [ -mm ] [ -a ] [ -e ] [ -4 num ] [ w num ] [ -p ] [ -P ] file ... 

DESCRIPnON 

Style analyzes the surface characteristics of the writing style of a document It reports on readability, 
sentence length and structure, word length and usage, verb type, and sentence openers. Because style 
runs deroff before looking at the text formatting header files should be included as part of the input 
The defaidt macro package -ms may be ov^dden with the flag -mm. The flag -ml, which causes 
deroff to skip lists, should be used if the docum^t contains many lists of non-sentences. The other 
options are used to locate sentences with certain characteristics. 

-a print all sentences with their length and readability index. 

-e print all sentences that begin with an expletive. 

-p print all s^tences that contain a passive verb. 

-Innm print all s^tences longa than num. 

print all s^tences whose readability index is greater than num. 

-P print parts of speech of the words in the document 

SEE ALSO 

deroff(l), diction(l) 

BUGS 

Use of non-standard formatting macros may cause inconrect sentence breaks. 
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NOTE 


NOT PRESENT IN WOLLONGONG’S EUNICE! 


NAME 

su - substitute user id temporarily 
SYNOPSIS 

SU [ ^ ] [ - ] [ userid ] 

DESCRIPTION 

Su demands the password of the specified userid, and if it is given, changes to that userid and invokes 
the Shell s/i(l) or csh(\) without changing the current directory. The user environment is unchanged 
except ftn* HOME and SHELL, which are taken from the password file for the user being substituted 
(see environ (7)). The new user ID stays in force until the Shell exits. 

If no userid is specified, “root” is assumed. Only users in the “wheel” group (group 0) can su to 
“root”, even wiA the root password. To remind the supCT-user of his responsibilities, the Shell substi¬ 
tutes *#’ for its usual prompt. 

The -f option prevents csh(l) from executing the .cshrc file; thus making su start iq) faster. 

The - option simulates a full login. 

EUNICE NOTES 

Not implemented in EUNICE. 

SEE ALSO 

sh(l), csh(l) 
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NAME 

sum - sum and count blocks in a file 

SYNOPSIS 

sum file 

DESCRIPTION 

Sum calculates and prints a 16-bit checksum for the named file« and also prints the number of blocks in 
the file. It is typically used to look for bad spots* or to validate a ^e communicated over some 
transmission line. 

SEE ALSO 

wc(l) 

DIAGNOSTICS 

‘Read error’ is indistinguishable from end of file on most devices; check the block count. 
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NAME 

symorder - rearrange name list 
SYNOPSIS 

symorder orderlist symbolfile 
DESCRIPTION 

Orderlist is a file containing symbols to be found in symbolfile, 1 symbol per line. 

Symbolfile is updated in place to put the requested symbols first in the symbol table, in the order 
specified. This is done by swapping the old symbols in the required spots with the new ones. If all of 
the order symbols are not found, an error is generated. 

This program was specifically designed to cut down on the overhead of getting symbols from /vmunix. 

SEE ALSO 

nlist(3) 
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NOT PRESENT IN WOLLONGONG’S EUNICE! 


NAME 

sysline - display system status on status line of a terminal 
SYNOPSIS 

sysline [ -bcdewhDilmpqrsj ] [ -H remote ] [ +N ] 

DESCRIPTION 

Sysline runs in the background and periodically displays system status information on the status line of 
the terminal. Not all terminals contain a status line. Those that do include the hl9, concept 108, Ann 
Arbor Ambassador, vtlOO, Televideo 925/950 and Freedom 100. If no flags are given, sysline displays 
the time of day, the current load average, the change in load average in the last 5 minutes, the number 
of users (followed by a ‘u’), the number of runnable process (followed by a ‘r’)[VAX only], the 
num^ of suspended processes (followed by a ‘s’)[VAX only], and the users who have logged on and 
off since the last status report. Finally, if new mail has arrived, a summary of it is printed. If there is 
unread mail in your mailbox, an asterisk will appear after the display of the number of users. The 
^play is normally in reverse video (if your terminal supports this in the status line) and is right 
justified to reduce distraction. Evwy fifth display is done in normal video to give the screen a chance 
to rest 

If you have a file named .who in your home directory, then the contents of that file is printed first One 
common use of this feature is to alias chdir, pushd, and popd to place the current directory stack in 
'/.who after it changes the new directory. 

The following flags may be given on the command line. 

Beep once every half hour and twice every hour, just like those obnoxious watches you 
keep hearing. 

Clear the status line for 5 seconds before each redisplay. 

Debug mode -- print status line data in human readable format 
Print out the current day/date before the time. 

Print out only the information. Do not print out the control commands necessary to put 
the information on the bottom line. This option is useful for putting the output of sysline 
onto the mode line of an emacs window. 

Window mode ~ print the status on the current line of the terminal, suitable for use 
inside a one line window. 

Print the load average on the remote host remote [VAX only]. If the host is down, or is 
not sending out rwhod packets, then the down time is printed instead. If the prefix "ucb” 
is present, then it is removed. 

Print out the host machine’s name after the time [VAX only]. 

Don’t print the names of people who log in and out 
Don’t check for mail 

Don’t report the number of {xocess which are runnable and suspended. 

Don’t display in reverse video. 

Update the status line every N seconds. The default is 60 seconds. 

Don’t print out diagnostic messages if something goes wrong when starting up. 

Print out the process id of the sysline process onto standard output upon startup. With 


-b 

-c 

-d 

-D 


-w 

-H remote 

-h 

-I 

-P 

-r 

+N 

-q 

-i 
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this inf n ntiarift n you can send the alarm signal to the sysline process to cause it to update 
immediately, sysline writes to the standard error, so you can redirect the standard output 
into a file to catch the process id. 

-s Print "short" form of line by left-justifying ijf escapes are not allowed in the status line. 

Some terminals (the Televideos and Freedom 100 for example) do not allow cursor 
movement (or other "intelligent" operations) in the status line. For these terminals, sys¬ 
line normally uses blanks to cause right-justification. This flag will disable the adding of 
the blanks. 

_j Force the sysline output to be left justified even on terminals capable of cursor movement 

on the status line. 

If you have a file .syslinelock in your home directory, then sysline will not update its statistics and 
write on your screen, it will just go to sleep for a minute. This is useful if you want to momentarily 
disable sysline. Note that it may take a few seconds from the time the lock file is created until you are 
guaranteed that sysline will not write on the screen. 

EUNICE NOTES 

Not implemented in EUNICE. 

FILES 

/etc/utmp 
/dev/kmem 

/usr/spool/rwho/whod.* 

${HOME)/.who 
$ {HOME)/.syslinelock 

AUTHORS 

John Foderaro 
Tom Ferrin ctmvetted it to use termct^. 

Mark Horton added terminfo ct^ability. 

BUGS 

If you interrupt the display then you may find your cursor missing or stuck on the status line. The best 
thing to do is reset the terminal. 

If there is too much for one line, the excess is thrown away. 


names of people who are logged in 

contains process table [VAX only] 

wlK>/uptime information for remote hosts [VAX only] 

informatitm to print on bottom line 

when it exists, sysline will not print 
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NOTE 


NOT PRESENT IN WOLLONGONG’S EUNICE! 


NAME 

systat - display system statistics (Hi a at 
SYNOPSIS 

systat [ -display ] [ re&esh-intoval ] 

DESCRIPTION 

Systat displays various system statistics in a %reai oriented £ashi(xi using the curses screen display 
library, curses(3X). 

While systat is running the screen is usually divided into two windows (an exception is the vmstat 
display which uses the entire socen). The iqiper window depicts the curroit syston load average. The 
information displayed in the lower window may vary, dqiending on user commands. The last line on 
the screen is reserved for usa input and error messages. 

By default systat displays the pr(x:esses getting the largest percentage of the processor in the lower win¬ 
dow. Other displays show sw^ space usage, disk i/o statistics (a la iostat(l)), virtual memory statistics 
(a la vmstat(l)X netwoik “mbuf ’ utilization, and networic connections (a la netstat(l)). 

Input is inteipreted at two different levels. A “global” command interpreter processes all keyboard 
input If this ccxnmand interpreter fails to recognize a command, the input line is passed to a per- 
display (x>mmand intopreter. This allows each display to have cotain display-specific commands. 

Certain characters cause immediate action by systat. These are 
"L Refresh the screen. 

*0 Print the name of the current “display” being shown in the lower window and the refresh 
interval. 

'Z Stop systat. 

Move the cursor to the command line and interpret the input line typed as a commancL While 
entering a ccHnmand the current char^ter oase, word erase, and line kill characters may be 
used 

The following conunands are intapreted by the “global” command interpreter, 
help 

Print the names of the available displays on the command line. 

load 

Print the load average ovct the past 1, 5, and 15 minutes on the command line. 

stop 

Stop refreshing the screen. 

[ start ] [ number ] 

Start (ccHitinue) refreshing the screen. If a seccHid, numaic, argument is provided it is inter¬ 
preted as a refresh interval (in seconds). Supplying only a number will set the refresh interval 
to this value. 

quit 

Exit systat. (This may be abbreviated to q.) 

The available displays are: 
pigs 

Display, in the lower window, those processes resident in main memory and getting the largest 
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iostat 


swap 


mbufs 


vmstat 

o 
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portion of the processor (the default display). When less than 100% of the processor is 
scheduled to user processes, the remaining time is accounted to the “idle” process. 

Display, in the lower window, statistics about processor use and disk throughput Statistics on 
processor use appear as bar grt^hs of the amount of time executing in us^ mode (“user”), in 
user mode running low priority processes (“nice”), in system mode (“system”), and idle 
(“idle”). Statistics on ^sk thixHighput show, for each drive, kilobytes of data transferred, 
numb^ of disk transacticHis performed, and average seek time (in milliseconds). This informa¬ 
tion may be displayed as bar graphs or as rows of numbers which scroll downward. Bar 
gn^hs are shown by default; commands specific to this display are discussed below. 

Display, in the low^ window, swap space in use on each swap device configured. Two sets of 
bar graphs are shown. The upp^ graph displays swap sp^e allocated to pure text segments 
(code), the lower gnq)h displays space allocated to stack and data segments. Allocated space is 
sorted by its size into buckets of size dmmin, dmmin*2, dmmin«4, to dmmax (to reflect 
allocation policies imposed by the s>^tem). The disk segment size, in sectors, is displayed 
along the left hand side of the text, and data and stack graphs. Space allocated to the user 
structure and page tables is not cuirratly accounted for. 

Display, in the lower window, the numb^ of mbufs allocated for particular uses, i.e. data, 
socket structures, etc. 

Take over the entire display and show a (rather crowded) ccxnpendium of statistics related to 
virtual memory usage, process scheduling, device interrupts, system name translation cacheing, 
disk i/o, etc. 

The upper left quadrant of the screen shows the numb^ of users logged in and the load aver¬ 
age ov^ the last one, five, and fifteen minute intervals. Below this line are statistics on 
memory utilization. The first row of the table reports memory usage only among active 
processes, that is processes that have run in the previous twenty seconds. The second row 
reports on memory usage of all processes. The first column reports on the number of physical 
pages claimed by processes. The second column rq)orts the number of physical pages that are 
devoted to read only text pages. The third and fourth columns report the same two figures for 
virtual pages, that is the number of pages that would be needed if all processes had all of their 
pages. Finally the last column shows the number of physical pages on the firee list 

Below the memory display is the disk usage display. It rqx>rts the number of seeks, transfers, 
and number of kilobyte blocks transfared per second averaged over the refiresh period of the 
display (by default five seconds). For some disks it also reports the average milliseconds per 
seek. Note that the system only keeps statistics on at most four disks. 

Below the disk display is a list of the avauge number of processes (over the last refresh inter¬ 
val) that are runnable (‘r’), in page wait (‘p’), in disk wait other than paging (‘d’), sleeping 
(‘s’), and swapped out but desiring to run (‘w’). Below the queue length listing is a numerical 
listing and a bar graph showing the amount of system (shown as *=’), user (shown as *>’), nice 
(shown as *-’), and idle time (shown as * ’). 

At the bottom left are statistics on name translations. It lists the number of names translated in 
the previous interval, the number and percentage of the translations that were handled by the 
system wide name translation cache, and the number and percentage of the translations that 
were handled by the per process name translation cache. 

Under the date in the upper right hand quadrant are statistics on paging and swapping activity. 
The first two columns report the average number of pages brought in and out per second over 


The Wollongong Group 


2 



SYSTAT(l) 


UNIX Programme’s Msmual 


SYSTAT(l) 


the last refresh interval due to page faults and the paging daemon. The third and fourth 
columns report the aveage number of pages brought in and oiu pe second over the last refresh 
interval due to swap requests initiated by the schedule. The first row of the display shows the 
aveage numbe of disk transfers per second ove the last refinesh interval; the second row of 
the display shows the average number of pages transferred pe second over the last refresh 
interval. 

Below the paging statistics is a line listing the average number of total reclaims (’Rec’), intran¬ 
sit blocking page faults (Tt*), swtq} text pages found in free list (‘F/S’), file system text pages 
found in firee list (‘F/F’), reclaims firom free list (‘RFL’), pages freed by the clock daemon 
(‘Fre’), and sequential process pages freed (‘SFr’) per second ov» the refresh interval. 

Below this line are statistics on the av^ge number of zero filled pages (‘zf) and demand 
filled text pages (‘xT) per second over the refiresh period. The first row indicates the number 
of requests that w«e resolved, the second row shows the numb^ that were set up, and the last 
row shows the p^xrentage of setup requests were actually used. Note that this percentage is 
usually less than 100%, however it may exceed 100% if a large number of requests are actu¬ 
ally used long after they were set up during a period when no new pages are being set up. 
Thus this figure is most interesting whra observed over a long time period, such as from boot 
time (see below on getting such a display). 

Below the page fill statistics is a column that lists the average number of context switches 
(‘Csw’), traps (‘Tip’), system calls (*Sys’), intemq)ts (‘Int’), charact^ ouq}ut to DZ ports 
using pseud^DMA (‘Pdm’), page faults (‘Fit’), pages scanned by the page daemon (‘Sen’), and 
revolutirais of the page daemon’s hand (‘Rev’) per second over the refresh interval. 

Running down the right hand side of the display is a breakdown of the interrupts being handled 
by the system. At the top of the list is the total intomipts per second over the time interval. 
TTie rest of the column breaks down the total on a device by device basis. Only devices that 
have interrupted at least once since boot time are shown. 

netstat 

Display, in the lower window, network coimections. By default, network servers awaiting 
requests are not displayed. Each address is displayed in the format “hosLport”, with each 
shown symbolically, when possible. It is possible to have addresses displayed numerically, 
limit the display to a set of ports, hosts, and/or protocols; see the list of commands below. 

Commands to switch between displays may be abbreviated to the minimum unambiguous prefix; for 
example, “io” for “iostat”. Certain inform^cxi may be discarded when the screen size is insufficient 
for display. For example, on a machine with 10 drives the iostat bar graph displays only 3 drives on a 
24 line terminal. When a bar gRq)h would ovctAow the allotted screen space it is truncated and the 
actual value is printed “over top’’ of the bar. 

The following commands are specific to the iostat display; the minimum unambiguous prefix may be 
supplied. 

numb^ 

Show the disk i/o statistics in numeric form. Values are displayed in numeric columns which 
scroll downward. 

bars Show the disk i/o statistics in bar graph form (default). 

msps Toggle the display of average seek time (the default is to not display seek times). 

The following commands are specific to the vmstat display; the minimum unambiguous prefix may be 
supplied. 

boot Display cumulative statistics since the system was booted. 

run Display statistics as a running total from the point this command is given. 
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time Display statistics averaged over the refresh interval (the default), 
zero Reset running statistics to zero. 

The following commands are common to each display which shows information about disk drives. 
These commands are used to select a set of drives to report on, should your system have more drives 
configured than can normally be displayed on the screen. 

ignore [ drives ] 

Do not display information about the drives indicated. Multiple drives may be specified, 
separated by spaces. 

display [ drives ] 

Display information about the drives indicated. Multiple drives may be specified, separated by 
spaces. 

The following command is specific to the netstat display; the minimum unambiguous prefix may be 
supplied. 

aU Toggle the displaying of server processes awaiting requests (this is the equivalent of the -a flag 
to netstat{\)). 

numbers 

Display network addresses numerically, 
names Display network addresses symbolically. 

The remaining commands are common to displays which rqx>rt network connections (currently only the 
netstat display). These commands may be used to select a specific set of connections for systat to 
report on. 

protocol 

Display only network connections using the indicated protocol (currently either “tcp” or 
“udp”). 

ignore [items] 

Do not display information about connections associated with the specified hosts or ports. 
Hosts and ports may be specified by name (“ucbmonet”, “ftp”), or numerically. Host 
addresses use the Internet dot notation (“128.32.0.9”). Multiple items may be specified with a 
single command by separating them with spaces. 

display [items] 

Display information about the connections associated with the specified hosts or ports. As for 
ignore, items may be names or numbera. 

show [portsihosts] 

Show, on the command line, the currently selected protocols, hosts, and ports. Hosts and ports 
which are being ignored are prefixed with a *!*. If ports or hosts is supplied as an argument to 
stww, thOT only the requested information will be displayed. 

reset Reset the port, host, and protocol matching mechanisms to the default (any protocol, port, or 
host). 

EUNICE NOTES 

Not implemented in EUNICE. 


FILES 


/vmunix 

/dev/kmem 

/dev/drum 

/etc/hosts 

/etc/networks 


for the namelist 

for information in main memory 
for information about swapped out processes 
for host names 
for network names 
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/etc/services for port names 
AUTHOR 

The unknown hacker. The pigs display is derived from a program of the same name written by Bill 
Reeves. 

BUGS 

Takes 2-10 p^ent of the cpu. Certain displays presume a 24 line by 80 character terminal. The swap 
space display should account for space allocated to the usot structure and page tables. The vmstat 
display looks out of place because it is (it was added in as a separate display rather than create a new 
program). 

The whole thing is pretty hokey and was included in the distribution under serious duress. 
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NAME 

tabs - set terminal tabs 
SYNOPSIS 

tabs [ -n ] [ terminal ] 

DESCRIPTION 

Tabs sets the tabs on a variety of terminals. Various terminal names given in term{l) are recognized; 
the default is, howev^, suitable for most 300 baud terminals. If the -n flag is present then the left 
margin is not indoited as is normal. 

SEE ALSO 

stty(l), term(7) 

BUGS 

It’s much better to use «et(l). 
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NAME 

tail - deliver the last part of a file 
SYNOPSIS 

taU [ ±numberObc][fr] ] [ file ] 

DESCRIPTION 

Tail copies the named file to the standard output beginning at a designated place. If no file is named, 
the standard input is used. 

Copying begins at distance +number from the beginning, or -number from the end of the input 
Number is counted in units of lines, blocks or characters, according to the appended option 1, b or c. 
When no units are specified, counting is by lines. 

Specifying r causes tail to print lines from the end of the file in reverse order. The default for r is to 
print the entire file this way. Specifying f causes tail to not quit at end of file, but rather wait and try 
to read repeatedly in hopes that the file will grow. 

SEE ALSO 

dd(l) 

BUGS 

Tails relative to the end of the file are treasured up in a buffer, and thus are limited in length. 

Various kinds of anomalous behavior may happen with charact^ special files. 
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NAME 

talk - talk to anoth^ user 
SYNOPSIS 

talk person [ ttyname ] 

DESCRIPTION 

Talk is a visual communication program which copies lines from your terminal to that of another user. 

If you wish to talk to someone on you own machine, then person is just the person’s login name. If you 
wish to talk to a user on another host, then person is of the form : 

hostluser or 
host.user or 
host:user or 
user@host 

though host@user is perhaps preferred. 

If you want to talk to a user who is logged in more than once, the ttyname argument may be used to 
indicate the apprq)riate terminal name. 

When first called, it sends the message 

Message from TalkDaemon@his_machine... 

talk: connection requested by your_name@your_machine. 

talk: respond with: talk your_name(§)your_machine 

to the us» you wish to talk to. At this point, the recipient of the message should reply by typing 
talk your_name@your_machine 

It doesn’t matter from which machine the recipient replies, as long as his login-name is the same. Once 
communication is established, the two parties may type simultaneously, with their output appearing in 
separate windows. Typing control L will cause the screen to be reprinted, while your erase, kill, and 
word kill characters will wwk in talk as normal. To exit, just type your interrupt charactCT; talk then 
moves the curscv to the bottom of the scre^ and restores the terminal. 

Permission to talk may be denied or granted by use of the mesg command. At the outset talking is 
allowed. Certain commands, in particular nroff and pr(l) disallow messages in order to prevent messy 
output 

EUNICE NOTES 

Not implemented in EUNICE. 

FILES 

/etc/hosts to find the recipient’s machine 

/etc/utmp to find the recipient’s tty 

SEE ALSO 

mesg(l), who(l), mail(l), write(l) 

BUGS 

The versicm of ta/k(l) released with 4.3BSD uses a protocol that is incompatible with the protocol used 
in the version released with 4.2BSD. 
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NAME 

tar - tape archiver 
SYNOPSIS 

tar [ key ] [ name ... ] 

DESCRIPTION 

Tar saves and restores multiple files on a single file (usually a magnetic tape, but it can be any file). 
Tar’s actions are controlled by the key argum«it The itey is a string of characters containing at most 
one function letter and possibly one or more function modifiers. Otha arguments to tar are file or 
directory names specifying which files to dump or restore. In all cases, appearance of a directory name 
refers to the files and (recursively) subdirectories of that directory. 

The function portion of the key is specified by one of the following letters: 

r The named files are written on the end of the tape. The c function implies this. 

X The named files are extracted from the tape. If the named file matches a directory whose 

contents had been written onto the tape, this directory is (recursively) extracted. The owner, 
modification time, and mode are restcoed (if possible). If no file argument is given, the entire 
content of the tape is extracted. Note that if multiple entries specifying the same file are on 
the tape, the last one overwrites all earli^. 

t The names of the specified files are listed each time they occur on the tape. If no file argu¬ 

ment is given, all of the names on the tape are listed. 

u The named files are added to the tape if either they are not already there or have been 
modified since last put on the tape. 

c Create a new tape; writing begins on the beginning of the tape instead of after the last file. 

This command implies r. 

The following characters may be used in addition to the letter which selects the function desired. 

o On output, tar normally places information specifying owner and modes of directories in the 

archive. Former versions of tar, when encountering this information will give error mes¬ 
sage of the form 

"<name>/: cannot create". 

This modifier will suppress the directory information. 

p This modifier says to restore files to their original modes, ignoring the present umask(2). 

Setuid and sticky information will also be restored to the super-user. 

0, 9 This modifier selects an alternate drive on which the tape is mounted. The default is drive 

0 at 1600 bpi, which is normally /dev/rmtS. 

V Normally tar does its work silently. The v (verbose) option makes tar print the name of 

each file it treats preceded by the function letter. With the t function, the verbose option 
gives more information about the tape entries than just their names. 

w Tar prints the action to be taken followed by file name, then wait for user confirmation. If a 

word beginning with ‘y’ is given, the action is done. Any other input means don’t do it. 

f Tar uses the next argument as the name of the archive instead of /dev/rmt?. If the name of 

the file is tar writes to standard output or reads from standard input, whichever is 
appropriate. Thus, /or can be used as the head or tail of a filter chain. Tar can also be used 
to move hierarchies with the command 

cd fromdir; tar cf -. I (cd todir, tar xf -) 

b Tar uses the next argument as the blocking factor for tape records. The default is 20 (the 

maximum). This option should only be used with raw magnetic tape archives (See f above). 
The block size is determined automatically when reading tapes (key letters ‘x’ and ‘t’). 
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1 tells tar to complain if it cannot resolve all of the links to the files dumped. If this is not 

specified, no ^ror messages are printed. 

m tells tar not to restore the modification times. The modification time will be the time of 

extraction. 

h Force tear to follow symbolic links as if they were normal files or directories. Normally, tar 

does not follow symbolic links. 

B Forces input and output blocking to 20 blocks per record. This option was added so that 

tar can work across a communications channel where the blocking may not be maintained. 

C If a file name is preceded by -C, then tar will perform a chdir(2) to that file name. This 

allows multiple directories not related by a close common parent to be archived using short 
relative path names. For example, to archive files from /usr/include and from /etc, one 
might use 

tar c -C /usr include -C / etc 

Previous restrictions dealing with tar's inability to properly handle blocked archives have been lifted. 
EUNICE NOTES 

When a tape has been created at a differ^t site, it is a common error to use an incorrect blocksize. 
The b option to specify the blocking factor to tar will not be recognized. It can be determined by mul¬ 
tiplying the blocking factor used to create the tape by 512. If the blocking factor used was 20, the 
blocksize specified in the command to mount the tape would be 10240. For example: 

% VMS MOUNT/FOR/BLOCK=10240 MTO: 

The default tape drive is drive 1, not 8, so the drive numbo* should be specified in the command. To 
determine the tape drive name in the UNIX environment, use ’Is -1 /dev I more’. The tape drives will 
be listed first and ’not found’. The device which tar references is the raw device, such as rmtO, rmtl, 
etc. At most sites, the tape drive is /dev/rmtO. For example to create a tape with 2 files on it: 

% tar evO filel file2 

TAR will not rewind the tape drive on close. 

This utility requires the EUNICE_1VERSI0N be turned ON. See letcleuniceleunice.com. 

FILES 

/dev/rmt? 

/tmp/tar* 

SEE ALSO 

tar(5) 

DIAGNOSTICS 

Complaints about bad key characters and tape read/write errors. 

Complaints if enough memory is not available to hold the link tables. 

BUGS 

There is no way to ask for the n-th occurrence of a file. 

Tape errors are handled ungracefully. 

The u option can be slow. 

The current limit on file name length is 100 charact^. 

There is no way selectively to follow symbolic links. 

When extracting tapes created with the r or u options, directory modification times may not be set 
correctly. 
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NAME 

tbl - format tables for nroff or troff 

SYNOPSIS 

tbl [ files ]... 

DESCRIPnON 

7b/ is a preprocessor for formatting tables for nrqff or troffO). The input files are copied to the stan¬ 
dard output, excq)t for lines between .TS and .TE command lines, which are assumed to describe tables 
and are reformatted. Details are giver in the /b/(l) reference manual 

EXAMPLE 

As an example, letting \t represent a tab (which should be typed as a genuine tab) the input 

.TS 

css 

CCS 

c c c 
Inn. 

Household Population 

TownNtHouseholds 

NtNumbeiNtSize 

BedminsteNt789St3.26 

Bernards Twp.\t3087Vt3.74 

Bemaidsville\t201SNt3.30 

Bound BrookNt342SVt3.04 

Branchbur^l644Nt3.49 

BridgewateiNt7897'43.81 

Far Hills\t24(N3.19 

.TE 


yields 


Housdiold Population 
Town Households 



Number 

Size 

Bedminsto: 

789 

3.26 

Barnards Twp. 

3087 

3.74 

Bemardsville 

2018 

3.30 

Bound Brook 

3425 

3.04 

Branchburg 

1644 

3.49 

Bridgewater 

7897 

3.81 

Far Hills 

240 

3.19 


If no arguments are given, tbl reads the standard input, so it may be used as a filter. Wh^ tbl is used 
with eqn or neqn the tbl command should be first, to minimize the volume of data passed through 
pipes. 

SEE ALSO 

troff(l), eqn(l) 

M. E. Lesk, TBL. 
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NAME 

tc - photoypesetter simulator 
SYNOPSIS 

tc [ -t ] [ -sN ] [ -pL ] [ file ] 

DESCRIPTION 

Tc interprets its input (standanl input default) as device codes for a Graphic Systems phototypesetter 
(cat). The standard ouq)ut of tc is intended for a Tektronix 4015 (a 4014 terminal with ASCII and APL 
character sets). The sixteen typesetter sizes are mapped into the 4014’s four sizes; the entire TROFF 
character set is drawn using the 4014*s character generator, using overstruck combinati(»is where neces¬ 
sary. Typical usage: 

troff -t file I tc 

At the end of each page tc waits for a newUne (empty line) from the keyboard before continuing on to 
the next pa^. In this wait state, the command e will suppress the screen »ase before the next page; 
sN will cause the next N pages to be skipped; and !line will send line to the shell. 

The ctxnmand line options are: 

-t Don’t wait between page^ for directing output into a file. 

-sN Skip the first N pages. 

-pL Set page length to L. L may include the scale factors p (points), i (inches), c (centimeters), 
and P (picas); default is picas. 

'-/ w' Multiply the default aspect ratio, 1.5, of a displayed page by l/w. 

SEE ALSO 

troff(l), plot(lG) 

BUGS 

Font distinctions are lost 

re’s character set is limited to ASCII in just one size. 

The aspect ratio option is unbelievable. 
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NAME 

tcopy - copy a mag tape 

SYNOPSIS 

tcopy src [ dest ] 

DESCRIPTION 

Tcopy is designed to copy magnetic tapes. The only assumption made about the tape is that there are 
two tape marks at the end. Tcopy with only a source tape specified will print information about the 
sizes of records and t^ files. If a destination is specified, dien, a copy will be made of the source 
tape. The blocking on the destination tape will be idoitical to that used on the source tape. Copying a 
tape will yield the same output as if just printing the sizes. 

SEE ALSO 

mtio(4) 
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NAME 

tee - pipe fitting 
SYNOPSIS 

tee [ -i ] [ -a ] [ file ] ... 

DESCRIPTION 

Tee transcribes the standard input to the standard output and makes copies in the files. Option -i ignores 
interrupts; option -a causes the output to be appended to the files rather than overwriting them. 
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NAME 

telnet - user interface to the TELNET protoo)! 

SYNOPSIS 

telnet [ host [ port ] ] 

DESCRIPTION 

Telnet is used to conununicate with another host using the TELNET protocol. If telnet is invoked 
without arguments, it enters command mode, indicated by its prompt C*tehiet>"). In this mode, it 
accepts and executes the commands listed below. If it is invoked with arguments, it performs an open 
command (see below) with those arguments. 

Once a ccxmection has been opened, telnet enters an input mode. The input mode ent^jed will be either 
"character at a time" or "line by line" depending on what the remote system supports. 

In "character at a time" mode, most text typed is immediately sent to the remote host for processing. 

In "line by line" mode, all text is echoed locally, and (normally) only completed lines are sent to the 
remote host The "local echo character" (initially ""E") may be used to turn off and on the local 
echo (this would mostly be used to enter passwords without the password being echoed). 

In either mode, if the localchars toggle is TRUE (the default in line mode; see below), the user's qidty 
intr, and flush charact^ are trapped locally, and sent as TELNET protocol sequences to the remote 
side. There are options (see toggle autoflush and toggle autosynch l^low) which cause this action to 
flush subsequent output to the terminal (until the remote host acknowledges the TELNET sequence) 
and flush previous terminal input (in the case of quit and intr). 

While coimected to a remote host, telnet command mode may be entered by typing the telnet "escape 
character" (initially "'‘]"). When in command mode, the normal terminal editing conventions are 
available. 

COMMANDS 

The following coimnands are available. Only enough of each command to uniquely identify it need be 
typed (this is also true for arguments to the mode, set, toggle, and display commands). 

open host [ port ] 

Open a coimection to the named host If no port numb^ is specified, telnet will attempt to 
ccmtact a TELNET saver at the default port The host specification may be either a host 
name (see hosts(5)) or an Internet address specified in the "dot notation" (see inet(3N)). 

close 

Close a TELNET session and return to command mode. 

quit 

Close any open TELNET sessitxi and exit telnet. An end of file (in command mode) will also 
close a session and exit 

z 

Suspend telnet. This command only works when the user is using the csh{\). 
mode type 

Type is either line (for "line by line" mode) or character (for "character at a time" mode). 
The remote host is asked for permission to go into the requested mode. If the remote host is 
enable of entering that mode, the requested mode will be entered. 

status 
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Show the current status of telnet. This includes the peer one is connected to, as well as the 
current mode. 

display [ argument... ] 

Displays all, or some, of the set and toggle values (see below). 

? [ command ] 

Get help. With no arguments, telnet prints a help summary. If a command is specified, telnet 
will print the help information for just that command. 

send arguments 

Sends one or more special characto^ sequences to the remote host The following are the argu¬ 
ments which may be specified (more th^ one argument may be specified at a time): 

escape 

Sends the current telnet esc^ charact^ (initially “"]”). 

synch 

Sends the TELNET SYNCH sequence. This sequence causes the remote system to 
discard all previously typed (but not yet read) input This sequence is sent as TCP 
urgent data (and may not work if the remote system is a 4.2 BSD system ~ if it 
doesn’t work, a lower case **r” may be echoed on the terminal). 

brk 

Sends the TELNET BRK (Break) sequence, which may have significance to the 
remote system. 

ip 

Sends the TELNET IP (Interrupt Process) sequence, which should cause the remote 
system to abort the currently running process. 

CU) 

Sends the TELNET AO (Abort Ouq)ut) sequence, which should cause the remote sys¬ 
tem to flush all output ft’om the remote system to the user’s terminal. 

ayt 

Sends the TELNET AYT (Are You There) sequence, to which the remote system 
may or may not choose to respond. 

ec 

Sends the TELNET EC (Erase Character) sequence, which should cause the remote 
syston to erase the last character entered. 

el 

Sends the TELNET EL (Erase Line) sequence, which should cause the remote system 
to erase the line currently being entered. 

ga 

Sends the TELNET GA (Go Ahead) sequence, which likely has no significance to the 
remote system. 

nop 

Sends the TELNET NOP (No OP«ation) sequence. 

? 

Prints out help information for the send command, 
set argument value 

Set any one of a number of telnet variables to a specific value. The special value “off’ turns 
off the function associated with the variable. The values of variables may be interrogated with 
the display command. The variables which may be specified are: 
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echo 

This is the value (initially **^E”) which, when in “line by line’’ mode, toggles 
between doing local echoing of entered characters (for normal processing), and 
suppressing echoing of ratered charact^ (fOT entering, say, a password). 

escape 

This is the telnet escape character (initially **"[”) which causes entry into telnet com¬ 
mand mode (when connected to a remote system). 

interrupt 

If telnet is in locakhars mode (see toggle localchars below) and the interrupt charac¬ 
ter is typed, a TELNET IP sequence (see send ip above) is sent to the remote host. 
The initial value for the interrupt character is taken to be the terminal’s intr character. 

quit 

If telnet is in localchars mode (see toggle localchars below) and the quit character is 
typed, a TELNET BRK sequence (see send brk above) is sent to the remote host. 
The initial value for the quit character is taken to be the terminal’s quit character. 

flushoutput 

If telnet is in localchars mode (see toggle localchars below) and the flushoutput char¬ 
acter is typed, a TELNET AO sequence (see send ao above) is sent to the remote 
host The initial value for the flush characto' is taken to be the terminal’s flush char¬ 
acter. 

erase 

If telnet is in localchars mode (see toggle localchars below), and if telnet is operating 
in “character at a dme’’ mode, then when this character is typed, a TELNET EC 
sequence (see send ec above) is sent to the remote system. The initial value for the 
erase character is taken to be the terminal’s erase character. 

kill 

If telnet is in localchars mode (see toggle localchars below), and if telnet is operating 
in “character at a time’’ mode, then when this characto: is typed, a TELNET EL 
sequence (see send el above) is sent to the remote system. The initial value for the 
kill character is taken to be the tominal’s kill character. 

eqf 

If telnet is operating in “line by line’’ mode, entering this character as the first char¬ 
acter on a line will cause this character to be sent to the remote system. The initial 
value of the eof characto' is taken to be the tominal’s eof character. 

toggle arguments... 

Toggle (between TRUE and FALSE) various flags that control how telnet responds to events. 
More than one argument may be specified. The state of these flags may be interrogated with 
the display command. Valid arguments 

localchars 

If this is TRUE, that the flush^ interrupt, quit, erase, and kill characters (see set 
above) are recognized locally, and transformed into (lK)pefully) £q)propriate TELNET 
control sequences (respectively ao, ip, brk, ec, and el; see send above). The initial 
value for diis toggle is TRUE in “line by line’’ mode, and FALSE in “character at a 
time’’ mode. 

autoflush 

If autoflush and localchars are both TRUE, then when the ao, intr, or quit characters 
are recognized (and transformed into TELNET sequences; see set above for details), 
telnet refuses to display any data on the user’s terminal until the remote system ack¬ 
nowledges (via a TELNET Timing Mark option) that it has processed those TELNET 
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sequences. The initial value for this toggle is TRUE if the terminal user had not done 
an "stty noflsh", otherwise FALSE (see stty(l)). 

autosynch 

If autosynch and localchars are both TRUE, then when either the intr or quit charac¬ 
ters is typed (see set above for descriptions of the intr and quit characters), the result¬ 
ing TELNET sequence sent is followed by the TELNET SYNCH sequence. This 
procedure should cause the remote system to begin throwing away aU peviously 
typed input until both of the TELNET sequences have been read and acted upon. 
The initM value of this toggle is FALSE. 

crmod 

Toggle carriage return mode. When this mode is enabled, most carriage return char- 
acto^ received from the remote host will be mapped into a carriage return followed 
by a line feed. This mode does not affect those char^ters Qrped by the user, only 
those received frcxn the remote host This mode is not very useful unless the remote 
host only sends carriage return, but never line feed. The initial value for this toggle is 
FALSE. 

debug 

Toggles sock^ level debugging (useful only to the .ruperuser). The initial value for 
this toggle is FALSE. 

options 

Toggles the display of some internal telnet protocol processing (having to do with 
TELNET options). The initial value for this toggle is FALSE. 

netdata 

Toggles the display of all network data (in hexadecimal format). The initial value for 
this toggle is FALSE. 

9 

Displays the legal toggle commands. 

EUNICE NOTES 

This file is pertinent only to customers who have Wollongong’s WINA’CP product 

BUGS 

There is no adequate way for dealing with flow control. 

On some remote systems, echo has to be turned off manually wl^n in “line by line’’ mode. 

There is enough settable state to justify a .telnetrc file. 

No capability for a .telnetrc file is provided. 

In “line by line’’ mode, the terminal’s eo/character is only recognized (and sent to the remote system) 
when it is the first character on a line. 


April 24, 1989 


The Wollongong Group 


4 



TEST(l) 


UNIX Programmer’s Manual 


TEST(l) 


NAME 

test - condition ctHnmand 

SYNOPSIS 

test expr 

DESCRIPnON 

test evaluates the expression expr, and if its value is true then returns zero exit status; otherwise, a non 
zero exit status is returned, test returns a non zero exit if there are no arguments. 

The following primitives are used to construct ej^r. 

-r file true if the file exists and is readable. 

-w file true if the file exists and is writable. 

•4 file true if the file exists and is not a directory. 

-d file true if the file exists exists and is a directory. 

-s file true if the file exists and has a size greater than zero. 


-t [ fildes ] 


true if the open file whose file deseriiHor number is fildes (1 by default) is associated with a 
terminal device. 


-z si 
-n si 
si = s2 
si !=s2 
si 


true if the length of string si is zero, 
true if the length of the string si is nonzero, 
true if the strings si and s2 are equal, 
true if the strings si and s2 are not equal, 
true if si is not the null string. 

nl -eq n2 true if the integers nl and n2 are algebraically equal. Any of the comparisons -ne, -gt, -ge, 
-4t, or -le may be used in place of -eq. 

These primaries may be combined with the following operators: 

! unary negation operator 

-a binary and operator 

-0 binary or operator 

( expr) parentheses for grouping. 

-a has highCT precedence than -o. Notice that all the operators and flags are sqparate arguments to test. 
Notice also that parentheses are meaningful to the Shell and must be escaped. 


SEE ALSO 

sh(l), find(l) 
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NAME 

tftp - trivial file transfer program 

SYNOPSIS 

tftp [ host ] 

DESCRIPTION _ 

Tftp is the user interface to the Internet TFTP (Trivial File Transfer Protocol), which allows users to 
transfer files to and from a remote machine. The remote host may be specified on the command line, in 
which case tftp uses host as the default host fw future transfers (see the connect command below). 

EUNICE NOTES 

This file is pertinent only to customers who have Wollongong’s WIN/TCP product 
COMMANDS 

Once tftp is running, it issues the prompt tftp> and recognizes the following commands: 

connect host-name [ port ] _ 

Set the host (and optionally port) fw transfix. Note that the TFTP protocol, unlike the FTP 
protocol, does not maintain ctHmections betweeen transfers; thus, the connect command does 
not actually create a connection, but merely remembers what host is to be used for transfers. 
You do not have to use the connect command; the remote host can be specified as part of the 
get or put commands. 

mode trantfer-mode 

Set the mode for transfers; transfer-mode may be one of ascii or binary. The default is ascii. 

put file 

put localfile remotefile 

put filel file2 ... fileN remote-directory 

Put a file or set of files to the specified remote file or directory. The destination can be in one 
of two forms: a filename on the remote host, if the host has already been specified, or a string 
of the form host:filename to specify both a host and filename at the same time. If the latter 
form is used, the hostname specifi^ becomes the default for future transfers. If the remote- 
directory form is used, the remote host is assumed to be a UNIX machine. 

get filename 

get remotename hcalname 
get filel filel ... fileN 

Get a file or set of files from the specified sources. Source can be in one of two forms: a 
filename on the remote host, if the host has already been specified, or a string of the form 
hostfilename to specify both a host and filename at the same time. If the latter form is used, 
the last hostname specified becomes the default for future transfers. 

quit Exit tftp. An end of file also exits, 
verbose Toggle verbose mode, 
trace Toggle packet tracing, 
status Show current status. 

rexmt retransmission-timeout 

Set the per-packet retransmission timeout, in seconds. 

timeout total-transmission-timeout 
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Set the total transmissitm timeout, in seconds, 
ascii Shorthand for "mode ascii" 
binary Shorthand for "mode binary" 

? [ command-name ... ] 

Print help information. 

BUGS 

Because there is no user-login or validation within the TFTP protocol, the remote site will probably 
have some sort of file-access restrictions in place. The exact methods are specific to each site and 
therefore difficult to document here. 
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NAME 

time - time a command 

SYNOPSIS 

time command 

DESCRIPTION 

The given commai^ is executed; after it is complete, time prints the el£^sed time during the command, 
the time spent in the system, and the time spent in execution of the command. Times are reported in 
seconds. 

On a PDP-11, the execution time can depend on what kind of memory the program happens to land in; 
the user time in MOS is often half what it is in core. 

The times are printed on the diagnostic output stream. 

Time is built in to cshO), using a different output format. 

EUNICE NOTES 

VMS does not differe ntia te betwe^ user time and system time. This results in both values being the 
same. 

BUGS 

Elapsed time is accurate to the second, while the CPU times are measured to the 100th second. Thus 
the sum of the CPU times can be iqp to a second larger than the elapsed time. 

Time is a built-in command to csh(l\ with a much different syntax. This command is available as 
“/bin/time” to csh users. 
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NAME 

tip, cu - connect to a remote system 
SYNOPSIS 

tip [ -V ] [ -speed ] system-name 
tip [ -V ] [ -speed ] phone-number 

cu phone-number [ -t ] [ -s speed ] [ -a acu ] [-A line ] [-* ] 

DESCRIPTION 

Tip and cu establish a full-duplex connection to anoth^ machine, giving the £^peaiance of being logged 
in directly on the remote cpu. It goes without saying that you must have a login on the machine (or 
equivalwit) to which you wish to connect. The (ueferred int^face is tip. The cu interface is included 
for those people attached to the “call UNIX** command of v^ion 7. This man ual page describes only 
tip. 

Typed characters are normally transmitted directly to the remote machine (which does the echoing as 
well). A tilde (*”*) appearing as the first character of a line is an escape signal; the following are 
recognized: 

D . Drop the connection and exit (you may still be logged in on the remote machine). 

"c [name] Change directory to name (no argument implies change to your home directory). 

’! Escape to a shell (exiting the shell will return you to tip). 

“> Copy file firom local to remote. Tip prompts for the name of a local file to transmit. 

'< Copy file from remote to local Tip prompts first for the name of the file to be sent, then 

for a command to be executed on the remote machine. 

"pfrom [ to ] 

Send a file to a remote UNIX host The put command causes the remote UNIX system to 
ran the command string “cat > *to***, while tip sends it the “firom** file. If the “to” file 
isn’t specified the “firom” file name is used. This command is actually a UNIX specific 
version of the “”>** command, 

"t from [ to ] 

Take a file firom a remote UNIX host As in the put command the “to” file defaults to the 
firom file name if it isn’t specified. The remote host executes the command string “cat 
’firom’;echo "A” to send the file to tip. 

Pipe the ouQ)ut firom a remote command to a local UNIX process. The command string 
sent to the local UNIX system is processed by the shell. 

Pipe the output firom a local UNIX process to the remote host. The command string sent to 
the local UNIX system is processed by the shell. 

Send a BREAK to the remote syst^. For systems which don’t support the necessary ioctl 
call the break is simulated by a sequence of line speed changes and DEL characters. 

Set a variable (see the discussion below). 

Stop tip (only available with job control). 

Stop only the “local side” of tip (only available with job control); the “remote side” of 
tip, the side that displays ouqiut firom the remote host, is left running. 

Get a summary of the tilde escapes 

Tip uses the file /etcAemote to find how to reach a particular system and to find out how it should 
operate while talkmg to the system; refo to remote (5) for a full description. F.ach system has a default 
baud rate with which to establish a connection. If this value is not suitable, the baud rate to be used 
may be specified on die command line, e.g. “tip -3(X) mds”. 
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When tip establishes a connection it sends out a connection message to the remote system; the default 
value, if any, is defined in /etc/remote. 

When tip prenpts for an argument (e.g. during setup of a file transfer) the line typed may be edited 
with the standard oase and kill characters. A null line in response to a prompt, or an interrupt, will 
abort the dialogue and return you to the remote machine. 

Tip guards against multiple users connecting to a remote system by opening modems and terminal lines 
with exclusive access, and by honoring the locking protocol used by uucp{\C). 

During file transfers tip provides a running count of the number of lines transferred. When using the ”> 
and ”< commands, the “eofiread” and “eofwrite” variables are used to recognize end-of-file when 
reading, and specify end-of-file when writing (see below). File transfers normally d^)end on tandem 
mode for flow control. If the remote system does not support tandem mode, “echocheck” may be set 
to indicate tip should synchronize with the remote system on the echo of each transmitted character. 

When tip must dial a phone number to connect to a system it will print various messages indicating its 
actions. Tip supports the DEC DN-11 and Racal-Vadic 831 auto-call-units; the DEC DF02 and DF03, 
Ventel 212 -h, Racal-Vadic 3451, and Bizcomp 1031 and 1032 integral call unil/modems. 

VARIABLES 

Tip maintains a set of variables which control its op^tion. Some of these variable are read-only to 
normal users (root is allowed to change anything of interest). Variables may be displayed and set 
through the “s” escape. The syntax for >^uriables is patterned after vi(l) and Mail(X). Supplying 
“all” as an argument to the set command displays all variables readable by the user. Alternatively, the 
user may request display of a particular variable by att^hing a *?’ to the end. For example “escape?” 
displays the current escape character. 

Variables are numeric, string, character, or boolean values. Boolean variables are set merely by speci¬ 
fying their name; they may be reset by prepending a *!’ to the name. Other variable types are set by 
concatenating an *»’ and the value. The entire assignment must not have any blanks in it A single set 
command may be used to interrogate as well as set a number of variables. Variables may be initialized 
at run time by placing set commands (without the “”s” prefix in a file .tiprc in one’s home directory). 
The -V option causes tip to display the sets as they are made. Certain common variables have abbrevi¬ 
ations. The following is a list of common variables, their abbreviations, and their default values. 

beautify 

(bool) Discard unprintable characters wh^ a session is being scripted; abbreviated be. 
baudrate 

(num) The baud rate at which the ctmnection was established; abb:eviated ba. 
dialtimeout 

(num) When dialing a phone number, the time (in seconds) to wait for a connection to be esta¬ 
blished; abbreviated died. 

echocheck 

(bool) Synchronize with the remote host during file transf^ by waiting for the echo of the last 
character transmitted; default is off. 

eofread 

(str) The set of characters which signify and end-of-tranmission during a ”< file transfer com¬ 
mand; abbreviated eofr. 

eofwrite 

(str) The string sent to indicate end-of-transmission during a *’> file transfer command; abbrevi¬ 
ated eqfw. 

eol 

(str) The set of characters which indicate an end-of-line. Tip will recognize escape characters 
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only after an end-of-line. 

escape 

(char) The command prefix (escape) character; abbreviated es\ default value is 
exceptions 

(str) The set of characters which should not be discarded due to the beautification switch; 
abbreviated ex; default value is ‘*\f«\f\b’*. 

force 

(char) The character used to force literal data transmission; abbreviated fo\ default value is 
framesize 

(num) The amount of data (in bytes) to buffer between file system writes when receiving files; 
abbreviated fr. 

host 

(str) The name of the host to which you are connected; abbreviated ho. 

prompt 

(char) The character which indicates and end-of-line on the remote host; abbreviated pr; 
default value is This value is used to synchronize during date transfers. The count of 
lines transferred during a file transfa* command is based on recipt of this character. 

raise 

(bool) Upper case mapping mode; abbreviated ra; default value is off. When this mode is 
enabled, all lower case letters will be mapped to uppo* case by tip for transmission to the 
remote machine. 

raisechar 

(char) The input character used to toggle upper case moping mode; abbreviated rc; default 
value is **A’. 

record 

(str) The name of the file in which a session script is recorded; abbreviated rec; default value 
is “tip.record”. 

script 

(bool) Session scripting mode; abbreviated sc; default is off. When script is true, tip will 
record everything transmitted by the remote machine in the script record file specified in 
record. If the beautify switch is on. only printable ASCII characters will be included in the 
script file (those characters betwee 040 and 0177). The variable exceptions is used to indicate 
chartK^ters which are an exception to the normal beautification rules. 

tabexpand 

(bool) Expand tabs to spaces during file transfers; abbreviated tab; default value is false. Each 
tab is expanded to 8 spaces. 

verbose 

(bool) Verbose mode; abbreviated verb; default is true. When verbose mode is enabled, tip 
prints messages while dialing, shows the current number of lines transfnred during a file 
transfer (^rations, and more. 

SHELL 

(str) The name of the shell to use for the ”! command; default value is “/bin/sh”, or taken 
from the environment. 

HOME 

(str) The home directmy to use for the ”c command; default value is taken from the environ¬ 
ment 
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FILES 

/etc/remote 
/etc/phones 
$ {REMOTE} 

$ {PHONES} 

"/.tiprc 

/usr/spool/uuq)/LCK..* 


global system descriptions 
global phone number data base 
private system descriptions 
private phone numbers 
initialization file. 

lock file to avoid conflicts with uucp 


DIAGNOSTICS 

Diagnostics are, hopefully, self explanatory. 


SEE ALSO 

remote(5), phones(5) 


BUGS 

The full set of variables is undocumented and should, probably, be paired down. 
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NAME 

tk - paginator for the Tektronix 4014 
SYNOPSIS 

tk [ -t ] [ -^ ] [ -pL ] [ file ] 

DESCRIPTION 

The output of tk is intended for a Tektronix 4014 terminal. Tk arranges for 66 lines to fit on the screen, 
divides the screen into N columns, and contributes an eight space page offset in the (default) single¬ 
column case. Tabs, spaces, and backspaces are collected and plotted when necessary. Teletype Model 
37 half- and reverse-line sequences are interpreted and plotted. At the end of each page tk waits for a 
newline (empty line) firom the keyboard before continuing on to the next page. In this wait state, the 
command Icommand will send the command to the shell. 

The command line options are: 

-t Don’t wait between pages; for directing output into a file. 

-N Divide the screen into N columns and wait after the last column. 

-pL Set page length to L lines. 

SEE ALSO 

pr(l) 
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NAME 

tn3270 - full-screen remote login to IBM VM/CMS 

SYNOPSIS 

tn3270 sysname 

DESCRIPTION 

Tn3270 permits a full-screen, fiill-duplex connection from a VAX UNIX machine to an IBM machine 
running VM/CMS giving the appearance of being logged in directly to the remote machine on an IBM 
3270 terminal. Of course you must have an account on the machine to which you wish to connect in 
order to log in. Tn3270 looks to the user in many respects like the Yale ASCII Terminal Communica¬ 
tion System II. Tn3270 is actually a modification of the Arpanet TELNET user interface (see telneti\)) 
that interprets and generates raw 3270 control streams. 

Emulation of the 3270 terminal is done in the Unix process. This emulation involves mapping 3270- 
style commands from the host into appropriate sequences to control the user’s terminal screen. Tn3270 
uses curses Ox) and the letcitermcap file to do this. The emulation also involves simulating the special 
3270 keyboard keys (program function keys, etc.) by mapping sequences of keystrokes from the ASCII 
keyboard into appropriate 3270 control strings. This mapping is terminal dependent and is specified in 
a description file, Ietclmap3270, (see map3270(5)) or in an environment variable MAP3270 (see 
mset(l)). Any special function keys on the ASCII keyboard are used whenever possible. If an entry 
for the user’s terminal is not found, tn3270 looks for an entry for the terminal type unknown. If this is 
not found, tn3270 uses a default keyboard mapping (see map3270O))- 

The first character of each special keyboard mapping sequence is either an ASCII escape (ESQ, a con¬ 
trol character, or an ASCII delete (DEL). If the user types an unrecognized function key sequence, 
tn3270 sends an ASCII bell (BEL), or a visual bell if defined in the user’s termcap entry, to the user’s 
terminal and nothing is sent to the IBM host. 

If tn3270 is invoked without specifying a remote host system name, it enters local command mode, 
indicated by the prompt “m3270>”. In this mode, tn3270 accepts and executes the following com¬ 
mands: 


open 

connect to a remote host 

close 

close the current connection 

quit 

exit tn3270 

z 

suspend tn3270 

status 

print connection status 

? 

print help information 


Other common telnet commands are not available in tn3270. Tn3270 command mode may also be 
entered, after connecting to a host, by typing a special escape character (typically control-C). 

While in command mode, any host login session is still alive but temporarily suspended. The host 
login session may be resumed by entering an empty line (press the RETURN key) in response to the 
command prompt A session may be terminated by logging off the foreign host or by typing “quit” or 
“close” while in local command mode. 

FILES 

/etc/termcap 

/etc/map3270 

AUTHOR 

Greg Minshall 

SEE ALSO 

mset(l), telnet(l), termcap(3x), termcap(5), map3270(5), Yale ASCII Terminal Communication System II 
Program Description/Operator's Manual (IBM SB30-1911) 
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BUGS 

Performance is slow and uses system resources prodigiously. 

Not all 3270 functions are supported, nor all Yale enhancements. 
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NAME 

touch - update date last modified of a file 
SYNOPSIS 

touch [ -c ] [ -f ] file ... 

DESCRIPTION 

Touch attempts to set the modified date of each file. If a file exists, this is done by reading a character 
firom the file and writing it back. If a file does not exist, an attempt will be made to create it unless the 
-c option is specified. The -f option will attempt to force the touch in spite of read and write permis¬ 
sions on a file. 

EUNICE NOTES 

If the file exists, touch updates the modified date of the file by opening it with write mode. 

SEE ALSO 

utimes(2) 
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NAME 

tp - manipulate tape archive 
SYNOPSIS 

tp [ key ] [ name ... ] 

DESCRIPTION 

Tp saves and restores files on DECU^ or magtape. Its actions are controlled by the key argument. 
The key is a string of characters ctmtaining at most one function letter and possibly one or more func¬ 
tion modifiers. Oth^ arguments to the command are file or directory names specifying which files are 
to be dumped, restored, or listed. In all cases, appearance of a directory name refers to the files and 
(recursively) subdirectories of that directory. 

The function portion of the key is specified by one of the following letters: 

r The named files are written on the tape. If files with the same names already exist, they are 

replaced. ‘Same’ is determined by string comparison, so ‘./abc’ can never be the same as 
‘/usr/dmr/abc’ even if ‘/usr/dmr’ is the current directory. If no file argument is given, is 
the default 

u updates the tape, u is like r, but a file is replaced only if its modification date is later than 

the date stored on the tape; that is to say, if it has changed since it was dumped, u is the 
default command if none is given. 

d deletes the named files from the tape. At least one name argument must be given. This func¬ 

tion is not permitted on magtapes. 

X extracts the named files from the tape to the file system. The owner and mode are restored. 

If no file argument is given, the entire contents of the tape are extracted. 

t lists the names of the specified files. If no file argument is given, the entire contents of the 

tape is listed. 

The following characters may be used in addition to the letter which selects the function desired, 
m Specifies magtape as opposed to DECtape. 

0,...,7 This modifier selects the drive on which the tape is mounted. For DECtape, x is default; 
for magtape ‘0’ is the default 

v Normally tp does its work silendy. The v (verbose) option causes it to type the name of 

each file it treats preceded by the function letter. With the t function, v gives more infor¬ 
mation about the tape entries than just the name. 

c means a fresh dump is being created; the tape directory is cleared before beginning. Usable 

only with r and u. This option is assumed with magtape since it is impossible to selectively 
overwrite magtape. 

i Errors reading and writing the tape are noted, but no action is taken. Normally, errors 

cause a return to the command level. 

f Use the first named file, rather than a tape, as the archive. This option currently acts like 

m; i.e. r implies c, and neither d nor u are permitted. 

w causes tp to pause before treating each file, type the indicative letter and the file name (as 

with v) and await the user’s response. Response y means ‘yes’, so the file is treated. Null 
response means ‘no’, and the file does not take part in whatever is being done. Response x 
means ‘exit’; the tp command terminates immediately. In the x function, files previously 
asked about have been extracted already. With r, u, and d no change has been made to the 
tape. 
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FILES 

/dev/tap? 

/devMit? 

SEE ALSO 

ar(l), tar(l) 

DIAGNOSTICS 

Several; the non-obvious one is ‘Phase error’, which means the file changed after it was selected for 
dumping but before it was dumped. 

BUGS 

A single file with several links to it is treated like several files. 

Binary-coded control information makes magnetic tapes written by tp difficult to carry to other 
machines; tar{\) avoids the problem. 
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NAME 

tr - translate characters 
SYNOPSIS 

tr [ -cds ] [ stringl [ string2 ] ] 

DESCRIPTION 

Tr copies the standard input to the standard output with substitution or deletion of selected characters. 
Input characters found in stringl are m^ped into the corresponding characters of string2. When 
stringl is short it is padded to the length of stringl by duplicating its last character. Any combination 
of the options -cds may be used: -c complements the set of characters in stringl with respect to the 
universe of characters whose ASCII codes are 01 through 0377 octal; -d deletes all input characters in 
stringl; -s squeezes all strings of repeated output characters that are in stringl to single characters. 

In either string the notation a-b means a range of characters from a to b in increasing ASCII order. 
The character V followed by 1, 2 or 3 octal digits stands for the character whose ASCII code is given 
by those digits. A ‘V followed by any other character stands for that character. 

The following example creates a list of aU the words in ‘file!’ one per line in ‘file2’, where a word is 
taken to be a maximal string of alphabetics. The second string is quoted to protect ‘V from the Shell. 
012 is the ASCII code for newline. 

tr -cs A-Za-z ^^12' <filel >file2 


SEE ALSO 

ed(l), ascii(7), expand(l) 

BUGS 

Won’t handle ASCII NUL in stringl or stringl; always deletes NUL from input 
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NAME 

troff, nroff - text formatting and typesetting 


SYNOPSIS 

troff [ option ] ... [ file ] ... 
nroff [ option ] ... [ file ]... 

DESCRIPTION 

Trojf formats text in the named files for printing on a Graphic Systems C/A/T phototypesetter; nroff is 
used for for typewriter-like devices. Their capabilities are described in the NroffUroff user’s manual. 

If no file argument is present, the standard input is read. An argument consisting of a single minus (-) 
is taken to be a file name corresponding to the standard input. The options, which may appear in any 
order so long as they appear before the files, are: 

-o/wr Print only pages whose page numbers appear in the comma-separated list of numbers and 
ranges. A range N-M means pages N through Af; an initial -N means from the beginning to 
page N\ and a final N- means from N to the end. 

-nA^ Number first generated page N. 

sN Stop every N pages. Nroff will halt prior to every N pages (default N=l) to allow paper load¬ 
ing or changing, and will resume upon receipt of a newline. Troff will stop the photo¬ 
typesetter every N pages, produce a trailer to allow changing cassettes, and resume when the 
typesetter’s start button is pressed. 

-mname Prepend the macro file /usr/lib/tmac/tmac.name to the input files. 

-roN Set register a (one-character) to N. 

-i Read standard input after the input files are exhausted. 

-q Invoke the simultaneous input-output mode of the rd request. 

Troff only 

-t Direct output to the standard output instead of the phototypesetter. 

-f Refrain from feeding out paper and stopping phototypesetter at the end of the run. 

-w Wait until phototypesetter is available, if currently busy. 

-b Report whether the phototypesetter is busy or available. No text processing is done. 

-a Send a printable ASCII approximation of the results to the standard output. 

-pN Print all characters in point size N while retaining all prescribed spacings and motions, to 

reduce phototypesetter elapsed time. 

-Ffontdir 

The directory fontdir contains the font width tables instead of the default directory 
/usr/lib/fonts. This option can be used to produce output for devices besides the photo¬ 
typesetter. 

If the file lusriadmitracct is writable, keeps phototypesetter accounting records there. The integrity 
of that file may be secured by making troff a ’set user-id’ program. 


FILES 


/tmp/ta* 

/usrAib/tmac/tmac. ♦ 

/usr/lib/term/* 

/usr/lib/font/* 

/dev/cat 

/usr/adm/tracct 


temporary file 
standard macro files 
terminal driving tables for nroff 
font width tables for troff 
phototypesetter 

accounting statistics for /dev/cat 
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SEE ALSO 

J. F. Ossanna, Nroff/Troff user’s manual 
B. W. Kemighan, A TROFF Tutorial 
eqn(l), tbl(l), ms(7), me(7), man(7), col(l) 
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NAME 

tipatch - trace patch 

SYNOPSIS 

trpatch [ file ]... 

DESCRIPTION 

Trpatch changes the header information in an executable so it can be installed on a VMS 4.0 system. It 
is only necessary to run trpatch on programs which are to be installed. 

VMS 4.0 changed the header information on an executable file. There are three entry points: to the 
VMS debugger, to the start of executable code, and a null entry. In a normal file, the debugger will 
simply return to the second entry point if the debugger is not explicitly invoked. The executable code 
then runs. With VMS 4.0, an executable with such an header cannot be installed. Trpatch will shift 
the code entry points such that they become: the start of executable code, a null entry and another null 
entry. The INSTALL utility can then use the executable. 

Use of trpatch has the same effect as using the -notrace flag to the ld(l) sequence. 

EUNICE NOTES 

This is a EUNICE specific command. 

SEE ALSO 
ld(l) 

FILES 

/usr/eun/trpatch 
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NAME 

true, false - provide truth values 

SYNOPSIS 

true 

false 

DESCRIPTION 

True and false are usually used in a Bourne shell script They test for the appropriate status "true" or 
"false" before running (or failing to run) a list of commands. 

EXAMPLE 


while true 
do 

command list 
done 

SEE ALSO 

csh(l), sh(l). false(l) 

DIAGNOSTICS 

True has exit status zero. 
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NAME 

tset - terminal dependent initialization 
SYNOPSIS 

tset [ options ] [ ^ [ident][test baudrate]:type ] ... [ type ] 

reset [ options ] [ -m [ident][test baudraie]:type ] ... [ type ] 

DESCRIPTION 

Tset sets up your terminal when you first log in to a UNIX system. It does terminal dependent process¬ 
ing such as setting erase and kill characters, setting or resetting delays, sending any sequences needed 
to properly initialized the terminal, and the like. It first determines the type of terminal involved, and 
then does necessary initializations and mode settings. The type of terminal attached to each unk port 
is specified in the /etclttys(5) database. Type names for terminals may be found in the termcap(5) data¬ 
base. If a port is not wired permanently to a specific terminal (not hardwired) it will be given an 
appropriate generic identifier such as dialup. 

In the case where no arguments are specified, tset simply reads the terminal type out of the environment 
variable TERM and re-initializes the terminal. The rest of this manual concerns itself with mode and 
environment initialization, typically done once at login, and options used at initialization time to deter¬ 
mine the terminal type and set up terminal modes. 

When used in a startup script {.profile for sh{i) users or .login for csh{l) users) it is desirable to give 
information about the type of terminal you will usually use on ports which are not hardwired. These 
ports are identified in /etcittys as dialup or plugboard or arpanet, etc. To specify what terminal type 
you usually use on these ports, the (map) option flag is followed by the appropriate port type 
identifier, an optional baud rate specification, and the terminal type. (The effect is to “map” from 
some conditions to a terminal type, that is, to tell tset “If I’m on this kind of port, guess that I’m on 
that kind of terminal”.) If more than one mapping is specified, the first applicable mapping prevails. A 
missing port type identifier matches all identifiers. Any of the alternate generic names given in termcap 
may be used for the identifier. 

A baudrate is specified as with stty{l), and is compared with the speed of the diagnostic output (which 
should be the control terminal). The baud rate test may be any combination of: >, @, <, and !; @ 
means “at” and ! inverts the sense of the test To avoid problems with metacharacters, it is best to 
place the entire argument to -m within characters; users of csh{l) must also put a ‘V’ before any 
“!” used here. 

Thus 

tset -m 'dialup>3()0:adm3a' -m dialup:dw2 -m 'plugboard:?adm3a' 

causes the terminal type to be set to an admSa if the port in use is a dialup at a speed greater than 300 
baud; to a dw2 if the port is (otherwise) a dialup (i.e. at 300 baud or less). (NOTE: the examples 
given here appear to take up more than one line, for text processing reasons. When you type in real 
tset commands, you must enter them entirely on one line.) If the type finally determined by tset begins 
with a question mark, the user is asked if s/he really wants that type. A null response means to use that 
type; otherwise, another type can be entered which will be used instead. Thus, in the above case, the 
user will be queried on a plugboard port as to whether they are actually using an adm3a. 

If no mapping applies and a final type option, not preceded by a -m, is given on the command line then 
that type is used; otherwise the type found in the letcjttys database will be taken to be the terminal 
type. This should always be the case for hardwired ports. 

It is usually desirable to return the terminal type, as finally determined by tset, and information about 
the terminal’s capabilities to a shell’s environment. This can be done using the - option; using the 
Bourne shell, ^/i(l): 

export TERM; TERM='tset - options..." 
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or using the C shell, csh(l): 

setenv TERM 'tset - options..' 

With csh it is preferable to use the following command in your .login file to initialize the TERM and 
TERMCAP environment variables at the same time. 

eval 'tset -s options...' 

It is also convenient to make an alias in your .cshrc: 

alias tset 'eval 'tset -s \!*'' 

This allows the command: 
tset 2621 

to be invoked at any time to set the terminal and environment Note to Bourne Shell users: It is not 
possible to get this aliasing effect with a shell script, because shell scripts cannot set the environment of 
their parent (If a process could set its parent’s environment, none of this nonsense would be necessary 
in the first place.) 

These commands cause tset to place the name of your t^minal in the variable TERM in the environ¬ 
ment; see environO). 

Once the terminal type is known, tset engages in terminal driver mode setting. This normally involves 
sending an initialization sequence to the terminal, setting the single character erase (and optionally the 
line-kill (full line erase)) characters, and setting special character delays. Tab and newline expansion 
are turned off during transmission of the terminal initialization sequence. 

On terminals that can backspace but not overstrike (such as a C3iT), and when the erase character is the 
default erase character (*#’ on standard systems), the erase character is changed to backspace 
(Control-H). 

The options are: 

-ec set the erase character to be the named character c on all terminals, the default being the back¬ 
space character on the terminal, usually "H. The character c can either be typed directly, or 
entered using the hat notation used h^. 

-kc is similar to -e but for the line kill character rather than the erase character, c defaults to 'X 
(for purely historical reasons). The kill characters is left alone if -k is not specified. The hat 
notation can also be used for this option. 

-ic is similar to -e but for the interrupt character rather than the erase character; c defaults to 'C. 
The hat notation can also be used for this option. 

- The name of the terminal finally decided upon is output on the standard output This is 
intended to be captured by the shell and placed in the environment variable TERM. 

-s Print the sequence of csh commands to initialize the environment variables TERM and 
TERMCAP based on the name of the terminal finally decided upon. 

-n On systems with the Berkeley 4BSD tty driver, specifies that the new tty driver modes should 
be initialized for this terminal. For a CRT, the CRTERASE and CRTKILL modes are set only 
if the baud rate is 1200 or greater. See tty(4) for more detail. 

-I suppresses transmitting terminal initialization strings. 

-Q suppresses printing the “Erase set to’’ and “Kill set to’’ messages. 

If tset is invoked as reset, it will set cooked and echo modes, turn off cbreak and raw modes, turn on 
newline translation, and restore special characters to a sensible state before any terminal dependent pro¬ 
cessing is done. Any special character that is found to be null or is reset to its default value. 
All arguments to tset may be used with reset. 
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This is most useful after a program dies leaving a terminal in a funny state. You may have to type 
“<LF>reset<LF>” to get it to work since <CR> may not work in this state. Often none of this will echo. 

EXAMPLES 

These examples all assume the Bourne shell and use the - option. If you use csh, use one of the varia¬ 
tions described above. Note that a typical use of tset in a .profile or .login will also use the -e and -k 
options, and often the -n or -Q options as well. These options have not been included here to keep the 
examples small. (NOTE: some of the examples given here appear to take up more than one line, for 
text processing reasons. When you type in real tset commands, you must enter them entirely on one 
line.) 

At the moment, you are on a 2621. This is suitable for typing by hand but not for a .profile, unless you 
are always on a 2621. 

export TERM; TERM='tset - 2621' 

You have an hl9 at home which you dial up on, but your office terminal is hardwired and known in 
/etc/ttys. 

export TERM; TERM='tset —m dialup:hl9' 

You have a switch which connects everything to everything, making it nearly impossible to key on 
what port you are coming in on. You use a vtKX) in your office at 9600 baud, and dial up to switch 
ports at 1200 baud from home on a 2621. Sometimes you use someone elses terminal at work, so you 
want it to ask you to make sure what terminal type you have at high speeds, but at 1200 baud you are 
always on a 2621. Note the placement of the question mark, and the quotes to protect the greater than 
and question mark from interpretation by the shell. 

export TERM; TERM='tset --m ’switch>1200:?vtl00’ -m ’switch<=:1200:2621’ 

All of the above entries will fall back on the terminal type specified in letcittys if none of the condi¬ 
tions hold. The following entry is appropriate if you always dial up, always at the same baud rate, on 
many different kinds of terminals. Your most common terminal is an admSa. It always asks you what 
kind of terminal you are on, defaulting to admSa. 

export TERM; TERM='tset - ?adm3a' 

If the file letcittys is not properly installed and you want to key entirely on the baud rate, the following 
can be used: 

export TERM; TERM='tset - -m ’>1200:vtl00’ 2621' 

Here is a fancy example to illustrate the power of tset and to hopelessly confuse anyone who has made 
it this far. You dial up at 12(X) baud or less on a conceptlOO, sometimes over switch ports and some¬ 
times over regular dialups. You use various terminals at speeds higher than 1200 over switch ports, 
most often the terminal in your office, which is a vtlOO. However, sometimes you log in from the 
university you used to go to, over the ARPANET; in this case you are on an ALTO emulating a 
dm2500. You also often log in on various hardwired ports, such as the console, all of which are prop¬ 
erly entered in letcittys. You want your erase character set to control H, your kill character set to con¬ 
trol U, and don’t want tset to print the “Erase set to Backspace, Kill set to Control U’’ message. 

export TERM; TERM='tset -e -k'U -Q —m ’switch<=:12(X):conceptl00’ -m ’switch:?vtl00’ 
-m dialup:conceptl00 -m arpanet:dm25(X)' 

FILES 

/etc/ttys port name to terminal type mapping database 
/etc/termcap terminal capability database 

SEE ALSO 

csh(l), sh(l), stty(l), ttys(5), termcap(5), environ(7) 
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BUGS 

The tset command is one of the first commands a user must master when getting started on a UNIX 
system. Unfortunately, it is one of the most complex, largely because of the extra effort the user must 
go through to get the environment of the login shell set Something needs to be done to make all this 
simpler, either the login{\) program should do this stuff, or a default shell alias should be made, or a 
way to set the environment of the parent should exist. 

This program can’t intuit personal choices for erase, interrupt and line kill characters, so it leaves these 
set to the local system standards. 
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NAME 

tsort - topological sort 

SYNOPSIS 

tsort [ file ] 

DESCRIPTION 

Tsort produces on the standard output a totally ordered list of items consistent with a partial ordering of 
items mentioned in the input file. If no file is specified, the standard input is understood. 

The input consists of pairs of items (nonempty strings) separated by blanks. Pairs of different items 
indicate ordering. Pairs of identical items indicate presence, but not ordering. 

SEE ALSO 

lorder(l) 

DIAGNOSTICS 

Odd data: there is an odd number of fields in the input file. 

BUGS 

Uses a quadratic algorithm; not worth fixing for the typical use of ordering a library archive file. 


April 25, 1989 


The Wollongong Group 


1 



TrY(i) 


UNIX Programmer’s Manual 


TTY(l) 


NAME 

tty - get terminal name 

SYNOPSIS 

tty [ -s ] 

DESCRIPTION 

Tty prints the pathname of the user’s terminal unless the -s (silent) is given. In either case, the exit 
value is zero if the standard input is a terminal and one if it is not 

DIAGNOSTICS 

‘not a tty’ if the standard input file is not a terminal. 
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NAME 

ul - do underlining 
SYNOPSIS 

ul [ -i ] [ -t terminal ] [ name ... ] 

DESCRIPTION 

Ul reads the named files (or standard input if none am given) and translates occurrences of underscores 
to the sequence which indicates underlining for the terminal in use, as specified by the environment 
variable TERM. The -t option overrides the t^minal kind specified in the environment. The file 
letcitermcap is read to determine the appropriate sequences for underlining. If the terminal is incapable 
of underlining, but is capable of a standout mode then that is used instead. If the terminal can over¬ 
strike, or handles underlining automatically, ul degenerates to cat(l). If the terminal cannot underline, 
underlining is ignored. 

The -i option causes ul to indicate underlining onto by a separate line containing appropriate dashes 
this is useful when you want to look at the underlining which is present in an nroff output stream 
on a crt-terminal. 

SEE ALSO 

man(l), nroff(l), colcrt(l) 

BUGS 

Nrqff usually ouq)uts a series of backspaces and underlines intermixed with the text to indicate under¬ 
lining. No attempt is made to optimize the backward motion. 
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NAME 

unifdef - remove ifdef ed lines 
SYNOPSIS 

unifdef [ -t -1 -c -Dsym -Ujym -idsym -iusym ] ... [ file ] 

DESCRIPTION 

Untfd^ is useful for removing ifdefed lines from a file while otherwise leaving the file alone. Unifdef 
is like a stripped-down C preprocessor it is smart enough to deal with the nested ifdefs, comments, 
single and double quotes of C syntax so that it can do its job, but it doesn’t do any including or 
interpretation of macros. Neither does it strip out comments, though it recognizes and ignores them. 
You specify which symbols you want defined -Dsym or undefined -\}sym and the lines inside those 
ifdefs will be copied to the output or removed as appropriate. The ifdef, ifndef, else, and endif lines 
associated with sym will also be removed. Ifdefs involving symbols you don’t specify are untouched 
and copied out along with their associated ifdef, else, and endif lines. If an ifdef X occurs nested inside 
another ifdef X, then the inside ifdef is treated as if it were an unrecognized symbol. If the same sym¬ 
bol appears in more than one argument, only the first occurrence is significant. 

The -1 option causes unifdef to replace removed lines with blank lines instead of deleting them. 

If you use ifdefs to delimit non-C lines, such as comments or code which is under construction, then 
you must tell urufdef which symbols are used for that purpose so that it won’t try to parse for quotes 
and comments in those ifdefed lines. You specify that you want the lines inside certain ifdefs to be 
ignored but copied out with -‘idsym and 4ujy/n similar to -Dsym and -Usym above. 

If you want to use unifdef for plain text (not C code), use the -t option. This makes unifdef refrain 
from attempting to recognize comments and single and double quotes. 

Unifdef copies its output to stdout and will take its input from stdin if no file argument is given. If the 
-c argument is specified, then the operation of unifdef is complemented, i.e. the lines that would have 
been removed or blanked are retained and vice versa. 

SEE ALSO 

diff(l) 

DIAGNOSTICS 

Premature EOF, inappropriate else or endif. 

Exit status is 0 if output is exact copy of input, 1 if not, 2 if trouble. 

BUGS 

Does not know how to deal with cpp consructs such as 
#if defined(X) II defined(Y) 


AUTHOR 

Dave Yost 
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NAME 


uniq - report repeated lines in a file 


SYNOPSIS 

uniq [ -udc [ +n ] [ -n ] ] [ input [ output ] ] 

DESCRIPTION 

Uniq reads the input file comparing adjacent lines. In the normal case, the second and succeeding 
copies of repeated lines are removed; the remainder is written on the output file. Note that repeated 
lines must be adjacent in order to be found; see sortil). If the -u flag is used, just the lines that are 
not repeated in the original file are output The -d option specifies that one copy of just the repeated 
lines is to be written. The normal mode output is the union of the -u and -d mode outputs. 

The -c option supersedes -u and -d and generates an output report in default style but with each line 
preceded by a count of the number of times it occurred. 

The n arguments specify skipping an initial portion of each line in the comparison: 

-n The first n fields together with any blanks before each are ignored. A field is defined as a 
string of non-space, non-tab characters separated by tabs and spaces from its neighbors. 

+n The first n characters are ignored. Fields are skipped before characters. 

SEE ALSO 

sort(l), comm(l) 
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NAME 

units - conversion program 

SYNOPSIS 

units 

DESCRIPTION 

Units converts quantities expressed in various standard scales to their equivalents in other scales. It 
works interactively in this fashion: 

You have: inch 
You want: cm 

* 2J4000e+00 
/ 3.93701e-01 

A quantity is specified as a multiplicative combination of units optionally preceded by a numeric multi¬ 
plier. Powers are indicated by suffixed positive integers, division by the usual sign: 

You have: 15 pounds force/in2 
You want: atm 

♦ L02069e+00 
/ 9.79730e-Cl 

Units only does multiplicative scale changes. Thus it can convert Kelvin to Rankine, but not Cen¬ 
tigrade to Fahrenheit Most familiar units, abbreviations, and metric prefixes are recognized, together 
with a generous leavening of exotica and a few constants of nature including: 

pi ratio of circumference to diameter 

c speed of light 

e charge on an electron 

g acceleration of gravity 

force same as g 

mole Avogadro’s number 

water pressure head per unit height of water 

au astronomical unit 

‘Pound’ is a unit of mass. Compound names are run together, e.g. ‘lightyear’. British units that differ 
from their US counterparts are prefixed thus: ‘brgallon’. Currency is denoted ‘belgiumffanc’, ‘britain- 
pound’,... 

For a complete list of units, ‘cat /usr/lib/uniis’. 

FILES 

/usr/lib/units 

BUGS 

Don’t base your financial plans on the currency conversions. 
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NAME 

unixtovms - switch UNIX file to VMS file format 

SYNOPSIS 

unixtovms file 

DESCRIPTION 

The unixtovms command takes the UNIX file and adapts it to VMS requirements. VMS files are vari¬ 
able or fixed length record files with implied new lines. UNIX requires fixed length 512 byte records 
(last record may be truncated), with linefeed character to signify "End of Line". 

A dir/fiill will show: 

Record format: Variable length 
Record attributes: Carriage return 
There is no distinction in UNIX between text and data files. 

EUNICE NOTES 

This is a EUNICE specific command. Use unixtovms to convert files from another UNIX system 
(brought in, for example, by ’tar’ or NFS) or files such as shell scripts which have been created by I/O 
redirection. 

SEE ALSO 

vmstounix(lW) 
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NAME 

uptime - show how long system has been up 

SYNOPSIS 

uptime 

DESCRIPTION 

Uptime prints the current time, the length of time the system has been up, and the average number of 
jobs in the run queue over the last 1, 5 and 15 minutes. It is, essentially, the first line of a w(l) com¬ 
mand. 

FILES 

/vmunix system name list 

SEE ALSO 
w(l) 
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NAME 

users - compact list of users who are on the system 

SYNOPSIS 

users 

DESCRIPTION 

Users lists the login names of the users currently on the system in a compact, one-line format 

FILES 

/etc/utmp 

SEE ALSO 

who(l) 
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NAME 

UUCP - Unix to Unix copy 
SYNOPSIS 

UUCP [ -acCdfmr ] [ -nuser ] [ -ggrade ] [ sspool ] [ -xdebug ] source-file.... destination-file 
DESCRIPTION 

Uucp copies files named by the source-file arguments to the destination-file argument. A file name may 
be a pathname on your machine, or may have the form 

system-namelpathname 

where ‘system-name’ is taken from a list of system names that uucp knows about Shell metacharacters 
?*n appearing in the pathname part will be expanded on the appropriate system. 

Pathnames may be one of: 

(1) a full pathname; 

(2) a pathname preceded by "user; wh^ user is a userid on the specified system and is replaced 
by that user’s login directory; 

(3) a pathname prefixed by where " is expanded into the system’s public directory (usually 
/usr/spool/uucppublic); 

(4) a partial pathname, which is prefixed by the current directory. 

If the result is an erroneous pathname for the remote system, the copy will fail. If the destination-file is 
a directory, the last part of the source-file name is used. 

Uucp preserves execute permissions across the transmission and gives 0666 read and write permissions 
(see chmod(2)). 

The following options are interpreted by uucp. 

-a Avoid doing a getwd to find the current directory. (This is sometimes used for efficiency.) 

-c Use the source file when copying out rather than copying the file to the spool directory. (This 

is the default.) 

-C Copy the source file to the spool directory and transmit the copy. 

-d Make all necessary directories for the file copy. (This is the default.) 

-f Do not make intermediate directories for the file copy. 

-%grade 

Grade is a single letter/number; lower ASCII sequence characters will cause a job to be 
transmitted earlier during a particular conversation. Default is ‘n’. By way of comparison, 
Mux(lC) defaults to ‘A’; mail is usually sent at ‘C’. 

-m Send mail to the requester when the copy is complete. 

-nuser Notify user on remote system (i.e., send user mail) that a file was sent. 

-r Do not start the transfer, just queue the job. 

-sspool Use spool as the spool directory instead of the default 
-xdebug 

Turn on the debugging at level debug. 

FILES 

/usr/spool/uucp - spool directory 
/usr/lib/uucp/* - other data and program files 
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SEE ALSO 

uux(lC), mail(l) 

D. A. Nowitz and M. E. Lesk, A Dial-Up Network of UNIX Systems. 

D. A. Nowitz, Uucp Implementation Description. 

WARNING 

The domain of remotely accessible files can (and for obvious security reasons, usually should) be 
severely restricted. You will very likely not be able to fetch files by pathname; ask a responsible per¬ 
son on the remote system to send them to you. For the same reasons you will probably not be able to 
send files to arbitrary pathnames. 

BUGS 

All files received by uucp will be owned by the uucp administrator (usually UID 5). 

The -m option will only work sending files or receiving a single file. (Receiving multiple files 
specified by special shell characters ?*[] will not activate the -m option.) 

At present uucp cannot copy to a system several "hops" away, that is, a command of the form 
uucp myfile systeml!system2!system3!yourfile 
is not permitted. Use uusend(\C) instead. 

When invoking uucp from csh(l), the *!’ character must be prefixed by the ‘V escape to inhibit csh's 
history mechanism. (Quotes are not sufficient.) 

Uucp refuses to copy a file that does not give read access to “other”; that is, the file must have at least 
0444 modes. 
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NAME 

uuencode, uudecode - encode/decode a binary file for transmission via mail 
SYNOPSIS 

uuencode [ source ] remotedest I mail sysl!sys2!..!decode 
uudecode [ file ] 

DESCRIPTION 

Uuencode and uudecode are used to send a binary file via uucp (or other) mail. This combination can 
be used over indirect mail links even when uusend(lC) is not available. 

Uuencode takes the named source file (default standard input) and produces an encoded version on the 
standard output. The encoding uses only printing ASCII characters, and includes the mode of the file 
and the remotedest for recreation on the remote system. 

Uudecode reads an encoded file, strips off any leading and trailing lines added by mailers, and recreates 
the original file with the specified mode and name. 

The intent is that all mail to the user “decode” should be filtered through the uudecode program. This 
way the file is created automatically without human intervention. This is possible on the uucp network 
by either using sendmail or by making rmail be a link to Mail instead of mail. In each case, an alias 
must be created in a master file to get the automatic invocation of uudecode. 

If these facilities are not available, the file can be sent to a user on the remote machine who can 
uudecode it manually. 

The encode file has an ordinary text form and can be edited by any text editor to change the mode or 
remote name. 

SEE ALSO 

atob(n), uusend(lC), uucp(lQ, uux(lC), mail(l), uuencode(5) 

BUGS 

The file is expanded by 35% (3 bytes become 4 plus control information) causing it to take longer to 
transmit. 

The user on the remote system who is invoking uudecode (often uucp) must have write permission on 
the specified file. 
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NAME 

uulog - display UUCP log files 
SYNOPSIS 

uulog [ -s ] [ -u user ] 

DESCRIPTION 

Uulog queries a log of uucpilC) and uux(lQ transactions in the file /usr/spooI/uucp/LOGFILE. 

The options command uulog to print logging information: 
ssys ftint information about work involving system sys. 

-uuser Print information about work done for the specified user. 

FILES 

/usr/spool/uucp/LOGFILE 

SEE ALSO 

uucp(lQ, uux(lC). 

NOTES 

Very early releases of UUCP used separate log files for each of the UUCP utilities; uulog was used to 
merge the individual logs into a master file. This capability has not been necessary for some time and 
is no longer supported. 

BUGS 

UUCP’s recording of which user issued a request is unreliable. 

Uulog is little more than an overspecialized version of grepil). 
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NAME 

uuname - list names of UUCP hosts 

SYNOPSIS 

uuname [ -1 ] 

DESCRIPTION 

Uuname lists the UUCP names of known systems. The -I option returns the local system name; this 
may differ from the hostname (1) for the system if the hostname is very long. 

SEE ALSO 

uucp(lC), uux(lC). 


April 25, 1989 


The Wollongong Group 


1 



UUQ(IC) 


UNIX ProgramniCT’s Manual 


UUQ(IC) 



NAME 

uuq - examine or manipulate the uuq) queue 
SYNOPSIS 

uuq [ -1 ] [ -h ] [ -ssystem ] [ -nuser ] [ -djobno ] [ -rsdir ] [ -hbaud ] 

DESCRIPTION 

Uuq is used to examine (and possibly delete) entries in the uuq) queue. 

When listing jobs, uuq uses a format reminiscent of Is. For the long format, information for each job 
listed includes job number, number of files to transfer, user who spooled the job, number of bytes to 
send, type of command requested (S for sending files, R for receiving files, X for remote uucp), and file 
or command desired. 

Several options are available: 

-h Print only the summary lines for each system. Summary lines give system name, number 

of jobs for the system, and total number of bytes to send. 

-1 Specifies a long format listing. The default is to list only the job numbers sorted across the 

page. 

Limit output to jobs for systems whose system names begin with system. 

’■‘Uuser Limit output to jobs fw users whose login names begin with user. 

-djobno Delete job number Jobno (as obtained firom a previous uuq command) from the uucp queue. 

Only the UUCP Administrator is permitted to delete jobs. 

-rsdir Look for files in the spooling directory sdir instead of the default directory. 

-hbaud Use baud to compute the transfer time instead of the default 1200 baud. 

FILES 

/usr/spool/uucp/ Default spool directory /usr/spool/uucp/C./C.* Control files 

/\jST/spooyuucp/Dhostname./D.* Outgoing data files Aisr/spool/uucp/X./X.* Outgoing execu¬ 

tion files 

SEE ALSO 

uucp(lQ, uux(lC), uulog(lC), uusnap(8C) 

BUGS 

No information is available on work requested by the remote machine. 

The user who requests a remote uucp command is unknown. 

Uuq -I can be horrendously slow. 

AUTHOR 

Lou Salkind, New York University 
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NAME 

uusend - send a file to a remote host 
SYNOPSIS 

uusend [ -m mode ] sourcefile sysl!sys2!..!remotefile 
DESCRIPTION 

Uusend sends a file to a given location on a remote system. The system need not be directly connected 
to the local system, but a chain of uucp{l) links needs to connect the two systems. 

If the -m option is specified, the mode of the file on the remote end will be taken from the octal 
number given. Otherwise, the mode of the input file will be used. 

The sourcefile can be meaning to use the standard input Both of these options are primarily 
intended for internal use of uusend. 

The remotefile can include the “ userid syntax. 

DIAGNOSTICS 

If anything goes wrong any further away than the first system down the line, you will never hear about 
it 

SEE ALSO 

uux(l), uucp(l), uuencode(l) 

BUGS 

This command should not exist, since uucp should handle it 

All systems along the line must have the uusend command available and allow remote execution of it. 

Some UUCP systems have a bug where binary files cannot be the input to a uux command. If this bug 
exists in any system along the line, the file will show up severly munged. 
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NAME 

uux - Unix to Unix command execution 
SYNOPSIS 

uux [ - ] [ -cCILnprz ] [ -smame ] [ -ggrade ] [ -xdebug ] command-string 
DESCRIPTION 

Uux wiU gather zero or more files from various systems, execute a command on a specified system and 
then send standard output to a file on a specified system. 

The command-string is made up of one or more arguments that look like a Shell command line, except 
that the command and file names may be prefixed by system-namel. A null system-name is interpreted 
as the local system. 

File names may be one of 

(1) a full path name; 

(2) a path name preceded by " user where user is a login name on the specified system and is 
replaced by that user’s login directory; 

(3) a path name prefixed by "; where " is expanded to the system’s public directory (usually 
/usr/spool/uucppublic); 

(4) a partial pathname, which is prefixed by the current directory. 

As an example, the command 

uux "idiff usg!/usr/dan/filel pwba!/a4/dan/file2 > !”/dan/file.diff" 

will get the filel and file! files from the “usg” and “pwba” machines, execute a diff(l) command and 
put the results in file.diff in the local /usr/spool/uucppublic/dan/ directory. 

Any special shell characters, such as o;|, should be quoted either by quoting the entire command¬ 
string, or quoting the special characters as individual arguments. 

Uux will attempt to get all files to the execution system. For files that are output files, the file name 
must be escaped using parentheses. For example, the command 

uux a!wc b!/usr/filel Xc!/usr/file2 \) 

get /usr/filel from system “b” and send it to system “a”, perform a wc command on that file and send 
the result of the wc command to system “c”. 

Uux will notify you by mail if the requested command on the remote system was disallowed. This 
notification can be turned off by the -n option. 

The following options are interpreted by uux: 

- The standard input to uux is made the standard input to the command-string. 

-aname Use name as the user identification replacing the initiator user-id. 

-c Do not copy local file to the spool directory for transfer to the remote machine (this is the 
default). 

-C Force the copy of local files to the spool directory for transfer. 

-ggrade 

Grade is a single letter/number, from 0 to 9, A to Z, or a to z; 0 is the highest, and z is the 
lowest grade. The default is A; by comparison uucp{lC) defaults to n and mail is usually sent 
at grade C. Lower grades should be specified for high-volume jobs, such as news. 

-1 Try and make a link from the original file to the spool directory. If the link cannot be made, 
copy the file. 

-n Do not notify the user when the command completes. 
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-p Same as The standard input to uux is made the standard input to the command-string. 

-r Do not start the file transfer, just queue the job. 

-xdebug 

Produce debugging output on stdout The debug is a number between 0 and 9; higher numbers 
give more detailed information. Debugging is permitted only for privileged users (specifically, 
those with read access to L.sys(5). 

-z Notify the user only if the command fails. 

-L Start up uucico with the -L flag. This will force calls to be made to local sites only (see 
uucico{%C)). 

FILES 

/usr/spool/uucp spool directories 

/usr/lib/uucp/* UUCP configuration data and daemons 

SEE ALSO 

uucp(lQ, uucico(8C), uuxqt(8C). 

WARNING 

For security reasons, many installations will limit the list of commands executable on behalf of an 
incoming request from uux. Many sites will permit little more than the receipt of mail (see mail{\)) 
via uux. 

BUGS 

Only the first command of a shell pipeline may have a system-namel. All other commands are exe¬ 
cuted on the system of the first command. 

The use of the shell metacharacter * will probably not do what you want it to do. 

The shell tokens « and » are not implemented. 

When invoking uux from cj/i(l), the ‘1’ character must be prefixed by the ‘V escape to inhibit csh's 
history mechanism. (Quotes are not sufficient.) 
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NAME 

vacation - return “I am on vacation” indication 

SYNOPSIS 

vacation -I 
vacation user 

DESCRIPTION 

Vacation returns a message to the sender of a message telling that you are on vacation. The intended 
use is in a .forward file. For example, your .forward file might have: 

\eric, "Ivacation eric" 

which would send messages to you (assuming your login name was eric) and send a message back to 
the sender. 

Vacation expects a file .vacation.msg in your home directory containing a message to be sent back to 
each sender. It should be an entire message (including headers). For example, it might say: 

From: eric@ucbmonet.Berkeley£DU (Eric Allman) 

Subject: I am on vacation 

Delivered-By-The-Graces-Of: the Vacation program 

I am on vacation until July 22. If you have something urgent, 
please contact Joe Kalash <kalash@ucbmgres.Berkeley.EDU>. 

--eric 

This message will only be sent once a week to each unique sender. The people who have sent you 
messages are kept in the files .vacation.pag and .vacation.dir in your home directory. The -I option 
initializes these files, and should be executed before you modify your .forward file. 

If the -I flag is not specified, vacation reads the first line from the standard input for a UNIX-style 
“From” line to determine the sender. If this is not present, a nasty diagnostic is produced. Send- 
mail(S) includes the “From” line automatically. 

No message is sent if the initial “From” line includes the string ‘‘-REQUEST@” or if a ‘‘Precedence: 
bulk” or ‘‘Precedence: junk” line is included in the header. 

SEE ALSO 

sendmail(8) 
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NAME 

version - provides information about the EUNICE BSD version level 

SYNOPSIS 

version 

DESCRIPTION 

Version is used to display the release number of EUNICE BSD currently loaded on the system, 
EUNICE NOTES 

Version is a EUNICE BSD specific command. It is stored in lusrieun. 

SEE ALSO 

/etc/eunice/eunice.com 
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NAME 

vgrind - grind nice listings of programs 
SYNOPSIS 

vgrind [ -f ] [ - ] [ -t ] [ -n ] [ -x ] [ -W ] [ -sn ] [ -h header ] [ -d file ] [ -Uanguage ] name ... 
DESCRIPTION 

Vgrind formats the program sources which are arguments in a nice style using troff(l) Comments are 
placed in italics, keywords in bold face, and the name of the current function is listed down the margin 
of each page as it is encountered. 

Vgrind runs in two basic modes, filter mode or regular mode. In filter mode vgrind acts as a filter in a 
manner similar to The standard input is passed directly to the standard output except for lines 

bracketed by the trojf-like macros: 

.vS - starts processing 

.vE - ends processing 

These lines are formatted as described above. The output from this filter can be passed to trojf for out¬ 
put There need be no particular (xdering with eqn{\) or 

In regular mode vgrind accepts input files, processes them, and passes them to trqff(l) for output. 

In both modes vgrind passes any lines beginning with a decimal point without conversion. 

The options are: 

-f forces filter mode 

forces input to be taken from standard input (default if -f is specified ) 

-t similar to the same option in troffcsusing formatted text to go to the standard output 
-n forces no keyword bolding 

-X outputs the index file in a “pretty” format. The index file itself is produced whenever vgrind is 
run with a file called index in the current directory. The index of function definitions can then 
be run off by giving vgrind the -x option and the file index as argumenL 

-W forces output to the (wide) Versatec printer rather than the (narrow) Varian 

-s specifies a point size to use on output (exactly the same as the argument of a .ps) 

-h specifies a particular header to put on every output page (default is the file name) 

-d specifies an alternate language definitions file (default is /usr/lib/vgrindefs) 

-1 specifies the language to use. Currently known are PASCAL (-Ip), MODEL (-lm),C (-Ic or 

the default), CSH (-Icsh), SHELL (-Ish), RATFOR (-Ir), MODULA2 (-lmod2), YACC 
(-lyacc), ISP (-lisp), and ICON (-11). 

FILES 

index file where source for index is created 

/usr/lib/tmac/tmac.vgrind macro package 

/usr/lib/vfontedpr preprocessor 

/usr/lib/vgrindefs language descriptions 

AUTHOR 

Dave Presotto & William Joy 
SEE ALSO 

vlp(l), vtroff(l), vgrindefs(5) 

BUGS 

Vfontedpr assumes that a certain programming style is followed: 
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For C - fimction names can be preceded on a line only by spaces, tabs, or an asterisk. The 
parenthesized arguments must also be on the same line. 

For PASCAL — function names need to appear on the same line as the keywords/wncrzon or procedure. 

For MODEIL — function names need to appear on the same line as the keywords is beginproc. 

If these conventions are not followed, the indexing and marginal function name comment mechanisms 
will fail. 

More generally, arbitrary formatting styles for programs mostly look bad. The use of spaces to align 
source code fails miserably; if you plan to vgrind your program you should use tabs. This is somewhat 
inevitable since the font used by vgrind is variable width. 

The mechanism of ctags in recognizing functions should be used here. 

Filter mode does not work in documents using the -me or -ms macros. (So what use is it anyway?) 


April 25, 1989 


The Wollongong Group 


2 



VI(1) 


UNIX Programmer’s Manual 


VI(1) 


NAME 

vi - screen oriented (visual) display editor based on ex 
SYNOPSIS 

vi [ -t tag ] [ -r ] [ ^command ][-!][ -wn ] name ... 

DESCRIPTION 

Vi (visual) is a display oriented text editor based on ex{\). Ex and vi run the same code; it is possible 
to get to the command mode of ex from within vi and vice-versa. 

The Vi Quick Reference card and the Introduction to Display Editing with Vi provide full details on 
using vi. 

EUNICE NOTES 

"T is used by the VMS DCL to request the status of processes currently running. This is always turned 
on in the EUNICE environment. However, if vi is used as a foreign command from DCL, turn the 'T 
off by typing: 

$ SET NOCONTROL=T.PRIORITY VMS default protections is not used for file creation. Users 
should set their umask to whatever default permission is in their .login file. 

FILES 

See ex(l). 

SEE ALSO 

ex (1), edit (1), “Vi Quick Reference’’ card, “An Introduction to Display Editing with Vi’’. 

AUTHOR 

William Joy 

Mark Horton added macros to visual mode and is maintaining version 3 

BUGS 

Software tabs using *T work only immediately after the autoindent. 

Left and right shifts on intelligent terminals don’t make use of insert and delete character operations in 
the terminal. 

The wrapmargin option can be fooled since it looks at output columns when blanks are typed. If a 
long word passes tlu-ough the margin and onto the next line without a break, then the line won’t be bro¬ 
ken. 

Insert/delete within a line can be slow if tabs are present on intelligent terminals, since the terminals 
need help in doing this correctly. 

Saving text on deletes in the named buffers is somewhat inefficient 

The source command does not work when executed as tsource; there is no way to use the :append, 
:change, and nnsert commands, since it is not possible to give more than one line of input to a : 
escape. To use these on a :global you must Q to ex command mode, execute them, and then reenter 
the screen editor with vi or open. 
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NAME 

vipw - edit the password file 

SYNOPSIS 

vipw 

DESCRIPTION 

Vipw edits the password file while setting the ^propriate locks, and does any necessary processing after 
the password file is unlocked. If the password file is already being edited, then you will be told to try 
again later. The vi editor will be used unless the environment variable EDITOR indicates an alternate 
editor. Vipw performs a number of consistency checks on the password entry for root, and will not 
allow a password file with a “mangled” root entry to be installed. 

EUNICE NOTES 

This command is not used in EUNICE BSD. Instead, fetcleimiceladduser.com creates and modifies the 
fetclpassword file, because EUNICE BSD uses the VMS style verification to log users in to the system. 

SEE ALSO 

passwd(l), passwd(5), adduser(8), mkpasswd(8) 

FILES 

/etc/ptmp 
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NAME 

vlp - Format Lisp programs to be printed with nroff, vtroff, or troff 
SYNOPSIS 

vlp [ -p pointsize ] [ -d ] [ -f ] [ -1 ] [ -v ] [ -T tUlel ] filel [ -T title2 ] file2 ... 

DESCRIPTION 

Vlp formats the named files so that they can be run through nrofif, vtroff, or troff to produce listings that 
line-up and are attractive. The first non-blank character of each line is lined-up vertically, as in the 
source file. Comments (text beginning with a semicolon) are printed in italics. Each function’s name is 
printed in bold face next to the function. This format makes Lisp code look attractive when it is 
printed with a variable width font. 

Normally, vlp works as a filter and sends its output to the standard output. However, the -v switch 
pipes the output directly to vtroff. If no files are specified, then vlp reads from the standard input 

The following options are available: 

-p The -p switch changes the size of the text from its default value of 8 points to one of 6, 8, 10, 
or 12 points. Once set, the point size is used fear all subsequent files. This point size does not 
apply to embedded text (see -/below). 

-d The -d switch puts vlp into debugging mode. 

-f Vlp has a filtered mode in which all lines are passed unmodified, except those lines between 
the directives .Ls and .Le. This mode can be used to format Lisp code that is embedded in a 
document The directive .Ls takes an optional argument that gives the point size for the 
embedded code. If not size is specified, the size of the surrounding text is used. 

-1 The -1 switch prevents vlp firom placing labels next to functions. This switch is useful for 
embedded Lisp code, where the labels would be distracting. 

-V This switch cause vlp to send its output to vtroff rather than the standard output 

-T A title to be printed on each page may be specified by using the -T switch. The -T switch 

applies only to the next file name given. Titles are not printed for embedded text (see -f, 
above). This switch may not be used if vlp is reading firom the standard input 

FILES 

/usr/lib/vlpmacs troff/nroff macros 

AUTHOR 

Originally written by John K. Foderaio, with additional changes by Kevin Layer and James Lams. 

SEE ALSO 

vgrind(l), lisp(l) 

BUGS 

vlp transforms \ into W so that it will be printed out. Hence, troff commands cannot be embedded in 
Lisp code. 
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NAME 

vms - execute VMS commands from EUNICE BSD shells 
SYNOPSIS 

vms [ -vt ] vms_command 
DESCRIPTION 

vms allows EUNICE BSD users to execute VMS commands without leaving the shell. The VMS com¬ 
mand is entered normally, but should usually be enclosed in single quotes (0 to thwart any shell substi¬ 
tutions. 

Output may be directed into a pipe for processing by EUNICE BSD utilities. 

By default, the output from the VMS command is sent to the standard output. However, interactive 
VMS commands (such as HELP or EDIT/EDT) will not prompt the terminal for input in this mode. If 
the -t option is specified, input and output will be directed to the terminal. Therefore, when -t is 
specified, it is not possible to redirect output from a command. 

The -V (verify) option prints the each step as it is executed by the VMS process. This is especially use¬ 
ful when the command invokes a DCL command procedure. 

Options may also be specified using the environment variable EUN_VMS_OPriONS. This variable 
defines the default flags to be used when the vms command is called. Most often, this is used for 
debugging. 

Arguments beginning with a percent sign (%) are taken to be UNIX-style file names, and are converted 
to their VMS equivalent file specification. 

EUNICE NOTES 

This is a EUNICE BSD specific command. 

EXAMPLES 

% vms -V "difT/parallel filel file2" 

executes the VMS command, DIFFERENCE, on the two files. The names are converted to VMS for¬ 
mat before being passed to the command. Since the -v option was given, the command is also printed. 

% vms show system/full | grep user_name 

displays the processes which belong, to the user with the UIC [user_name]. 

% vms -t help lexical 

gets VMS help on the DCL lexical functions. The prompts for subtopics will be made through the ter¬ 
minal. 

SEE ALSO 

csh(l) 

"VMS Guide to Using Command Procedures" 

BUGS 

Control-Y and control-C are sometimes sluggish when -t is not specified. Quite a few lines of output 
may be printed before the VMS process is stopped or killed. 
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System resources (CPU time, page faults, i/o, etc.) for the VMS subprocess are not reported back to 
EUNICE BSD. This makes the results of Ame(l ) too low. 

Some VMS programs detect that output is not a terminal, and create lines 132 columns wide. Some¬ 
times this is defeatable with an option, but often not 
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NAME 

vmsas - VMS output assembler 
SYNOPSIS 

vmsas [ -dl24 ] [ -L ] [ -W ] [ -V ] [ -J ] [ -R ] [ -t directory ] [ -o objfile ] [ name ... ] 
DESCRIPTION 

Vmsas assembles the named files, or the standard input if no file name is specified. The available flags 
are: 

-d Specifies the number of bytes to be assembled for offsets which involve forward or external 
references, and which have sizes unspecified in the assembly language. The default is -d4. 

-L Save defined labels beginning with a ‘L’, which are normally discarded to save space in the 
resultant symbol table. The compilers generate such temporary labels. 

-V Use virtual memory for intermediate storage, rather than a temporary file. 

-W Do not complain about errors. 

-J Use long branches to resolve jumps when byte-displacement branches are insufficient. This 
must be used when a compiler-generated assembly contains branches of more than 32k bytes. 

-R Make initialized data segments read-only, by concatenating them to the text segments. This 
obviates the need to run editor scripts on assembly code to make initialized data read-only and 
shared. 

-t Specifies a directory to receive the temporary file, other than the default /tmp. 

All undefined symbols in the assembly are treated as global. 

The output of the assembly is left on the file objfile; if that is omitted, a.out is used. The vmsas assem¬ 
bler ouQ)uts VMS type object code. 

EUNICE NOTES 

There are two assemblers provided lusrleunfvmsas and Ibinfas. The vmsas command is a EUNICE 
specific command. See cc(l) or f77(l) for more information. 

FILES 

/tmp/vmsas(** default temporary file 

a.out default resultant object file 

SEE ALSO 

ld(l), nm(l), adb(l), dbx(l), a.out(5), as(l), cc(l), n7(l). The EUNICE BSD Reference Manual, 
Auxiliary documentation Assembler Reference Manual. 

AUTHORS 

John F. Reiser 
Robert R. Henry 

BUGS 

-J should be eliminated; the assembler should automatically choose among byte, word and long 
branches. 
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NAME 

vmsld - VMS link editor 
SYNOPSIS 

vmsld [ option ] ... file ... 

DESCRIPTION 

Vmsld combines several object programs into one, resolves external references, and searches libraries. 
It is a modified copy of ld(l), which is to be used to load VMS style objects. This loader is used by 
default (instead of unixld(l)) by cc(l) and P7(l) if VMS style objects have been requested by setting 
LD_IMAGE to /usr/eun/vmsld. 

NOTE: ld(l) may default to either unixld(l) or vmsld(lW). To change this systemwide, see the system 
administrator for your system. To change this for a user’s account, see The EUNICE BSD Reference 
Manual, "Creating VMS and UNIX object files". 

In the simplest case, several object files are given, and vmsld combines them, producing an object 
module which can be executed. The output of vmsld is left in a.out This file is made executable only 
if no errors occurred during the load. 

The argument routines are concatenated in the ordo* specified. The entry point of the output is the 
beginning of the first routine. 

If any argument is a library, it is searched exactly once at the point it is encountered in the argument 
list. Only those routines defining an unresolved external reference are loaded. 

The symbols ‘_etext’, ‘_edata’ and ‘_end’ (‘etext’, ‘edata’ and ‘end’ in C) are reserved, and if referred 
to, are set to the first location above the program, the first location above initialized data, and the first 
location above all data respectively. It is erroneous to define these symbols. 

Vmsld understands several options. Except for -1, they should appear before the file names. 

-A This option specifies incremental loading, i.e. linking is to be done in a manner so that the 
resulting object may be read into an already executing program. The next argument is the 
name of a file whose symbol table will be taken as a basis on which to define additional sym¬ 
bols. Only newly linked material will be entered into the text and data portions of a.out, but 
the new symbol table will reflect every symbol defined before and after the incremental load. 
This argument must appear before any other object file in the argument list. The -T option 
may be used as well, and will be taken to mean that the newly linked segment will commence 
at the corresponding address (which must be a multiple of 1024). The default value is the old 
value of _end. 

-lx This option is an abbreviation for the library name /usr/libvms/libx.olb where x is a string. A 
library is searched when its name is encountered, so the placement of a -1 is significant. 

-M produce a primitive load map, listing the names of the files which will be loaded. 

-o The name argument after -o is used as the name of the vmsld output file, instead of a.out. 

-T The next argument is a hexadecimal number which sets the text segment origin. The default 

origin is 0. 

-t ("trace") Print the name of each file as it is processed. 

-u Take the following argument as a symbol and enter it as undefined in the symbol table. This 

is useful for loading wholly from a library, since initially the symbol table is empty and an 
unresolved reference is needed to force the loading of the first routine. 

-notrace 

Causes the loader to not insert traceback. This must be used when an image is to be installed. 
Refer to the VMS manuals for more information. This flag is specific to the vmsld(lW) pro¬ 
vided with EUNICE. 
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-noshare 

This option cancels the default which loads the shareable "C” images and will cause all rou¬ 
tines to be loaded out of the standard "C" library. This will produce an image which does not 
require the presence of the shareable C images. If this image is to be run on a VMS system 
without a EUNICE or UNIX license, read ”REX Capabilities and Obligations" in The EUN¬ 
ICE BSD Reference Manual and obtain the proper license. This option is also important if 
you are linking code which manipulates the EI^CE runtime system (e.g. code with # include 
<eunice/eunice.h> in it). This flag is specific to the vmsld(lW) provided with EUNICE. 

-nopObufs 

Sets the NOPOBUFS flag in the VMS image header and sets the IMGIOCNT to 250. This 
will keep RMS from intruding on PO space in those programs which are sensitive to the state 
of PO space. These are usually programs which do their own memory allocation and expect 
contiguous sbrks. Very few UNIX programs have this requirement (e.g adb and dd). Programs 
using the maUoc routines will not have any problems. Include /lib/prealloc.o for UNIX object 
files or /usr/libvms/prealloc.obj for VMS object files in the load to keep EUNICE from intrud¬ 
ing on PO space. The internal EUNICE data structures will be preallocated. This flag is 
specific to the vmsld(lW) provided with EUNICE. 

-vSHRBLEIMAGENAME 

Includes the shareable image SHRBLEIMAGENAME in the load. This flag is specific to the 
vinsld(lW) provided with EUNICE. 

Note that vmsld does not reference the variables set up by the aliases vmsobj or unixobj. Use 
cc or f77 for the load phase if these aliases are to be used or explicitly request /usr/eun/vmsld. 
See cc(l) and f77(l). 

-vmsdebug 

Symbol table so the VMS debugging can be used. This flag is specific to the loader provided 
with EUNICE. 


EUNICE NOTES 

This utility is specific to EUNICE, and not part of the normal 4.3 BSD distribution. 

FILES 

/usr/libvms/lib* .olb 
/usr/libvms/libc .olb 

a.out 

SEE ALSO 

as(l), ar(l), cc(l), ld(l), ranlib(l). The EUNICE BSD Reference Manual 

BUGS 

There is no way to force data to be page aligned. 


libraries references for vmsld (vmsobj) 
default library for vmsld; also default library 
with noshare option 
ouq)ut file 
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NAME 

vmsmail - send UNIX maU to the VMS mailer 

SYNOPSIS 

vmsmail [ name ] 

DESCRIPTION 

Vmsmail allows users of EUNICE to send standard input to the VMS mailer as an alternative to the 
UNIX mailer. A "Z will terminate the message. Mail can be sent by directly calling vmsmail or by 
creating an alias for user’s mail. 

EUNICE NOTES 

This is a EUNICE specific command. 

EXAMPLES 

If the alias ”vmail" in lusriliblaliases is as follows: 

vmailiuserl, user2,"l /usr/eun/vmsmail user3" 

then userl, and usei2 will receive UNIX mail, the mail for user3 will go through VMS mail. 

% /usr/eun/vmsmail user 
sends mail through VMS without use of alias. 
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NAME 

vmsname - give equivalent VMS file specification 
SYNOPSIS 

vmsname [pathname] 

DESCRIPTION 

The vmsname command enables EUNICE users to determine the VMS equivalent to any UNIX 
filename or pathname while still in a EUNICE shell. 

EUNICE NOTES 

This is a EUNICE-specific command. 

FILES 

/usr/eun/vmsname 

SEE ALSO 

vms(lW) 

EXAMPLES 

% set noglob; "vms dir/full ‘vmsname $HOME/t_file‘; set glob" 

It is important to turn off globbing otherwise the vms special characters such as [ will be interpreted by 
the shell. This is useful to have inside shell scripts and makefiles when vms specific commands are 
used. 
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NOTE 


NOT PRESENT IN WOLLONGONG’S EUNICE! 


NAME 

vmstat - repOTt virtual memory statistics 
SYNOPSIS 

vmstat [ -fsi ] [ drives ] [ interval [ count ] ] 

DESCRIPTION 

Vmstat delves into the system and normally reports certain statistics kept about process, virtual memory, 
disk, trap and cpu activity. If given a -f argument, it instead reports on the number of forks and vforks 
since system startup and the number of pages of virtual memory involved in each kind of fork. If given 
a -s argument, it instead prints the contents of the sum structure, giving the total number of several 
kinds of paging related events which have occurred since boot If given a -i argument, it instead 
reports on the number of interrupts taken by each device since system startup. 

If none of these options are given, vmstat will rqxjrt in the first line a summary of the virtual memory 
activity since the system has been booted. If interval is specified, then successive lines are summaries 
over the last interval seconds, “vmstat 5’* will print what the system is doing every five seconds; this 
is a good choice of printing interval since this is how often some of the statistics are sampled in the 
system; others vary every second, running the output for a while will make it apparent which are 
recomputed every second. If a count is given, the statistics are repeated count times. The format fields 
are: 

Procs; information about numbers of processes in various states. 

r in run queue 

b blocked for resources (i/o, paging, etc.) 

w runnable or short sleeper (< 20 secs) but swapped 

Memory: information about the usage of virtual and real memory. Virtual pages are considered active 
if they belong to processes which are running or have run in the last 20 seconds. A “page” here is 
1024 bytes. 

avm active virtual pages 

fire size of the free list 

Page: information about page faults and paging activity. These are averaged each five seconds, and 
given in units per second. 

re page reclaims (simulating reference bits) 

at pages attached (found in free list) 

pi pages paged in 

po pages paged out 

fr pages freed per second 

de anticipated short term memory shortfall 

sr pages scanned by clock algorithm, per-second 

up/hp/rk/ra: Disk operations per second (this field is system dependent). Typically paging will be split 
across several of the available drives. The number under each of these is the unit number. 

Faults: trap/interrupt rate averages per second over last 5 seconds. 


in 

(non clock) device interrupts per second 

sy 

system calls per second 

cs 

cpu context switch rate (switches/sec) 
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Cpu: breakdown of percentage usage of CPU time 

us user time for normal and low priority processes 

sy system time 

id cpu idle 

If more than 4 disk drives are configured in the system, vmstat displays only the first 4 drives, with 
priority given to Massbus disk drives (i.e. if both Unibus and Massbus drives are present and the total 
number of drives exceeds 4, then some number of Unibus drives will not be displayed in favor of the 
Massbus drives). To force vmstat to display specific drives, their names may be supplied on the com¬ 
mand line. 

EUNICE NOTES 

Not implemented in EUNICE. 

FILES 

/dev/kmem, /vmunix 

SEE ALSO 

systatiX), iostatil) 

The sections starting with “Interpreting system activity” in Installing and Operating 42bsd. 
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NAME 

vmstounix - switch VMS file to UNIX file format 

SYNOPSIS 

vmstounix file 

DESCRIPTION 

The vmstounix command takes the VMS file and adapts it to UNIX requirements. VMS files are vari¬ 
able or fixed length record files with implied new lines. UNIX requires fixed length 512 byte records 
(last record may be truncated), with linefe^ character to signify "End of Line". 

A dir/fiill will show: 

Record format: Fixed length 512 byte records 
Record attributes: None 

There is no distinction in UNIX between text and data files. 

EUNICE NOTES 

This is a EUNICE specific command. 

SEE ALSO 

unixtovms(lW) 

BUGS 

No single line in a VMS text file may exceed 511 characters, plus an EOL (End of Line). 
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NAME 

vwidth - make troff width table for a font 
SYNOPSIS 

vwidth fontfile pointsize > ftxx.c 
cc -c ftccx mv ftxz.o /usrAib/font/ftcx 

DESCRIPTION 

Vwidth translates from the width information stored in the vfont style format to the format expected by 
troff. Troff wants an object file in a.out(5) format (This fact does not seem to be documented any¬ 
where.) Troff should look directly in the font file but it doesn’t 

Vwidth should be used aftw editing a font with fed(l). It is not necessary to use vwidth unless you have 
made a change that would affect the width tables. Such changes include numerically editing the width 
field, adding a new character, and moving or copying a character to a new position. It is not always 
necessary to use vwidth if the physical width of the glyph (e.g. the number of columns in the bit 
matrix) has changed, but if it has changed much the logical width should probably be changed and 
vwidth run. 

Vwidth produces a C program on its standard output This program should be run through the C com¬ 
piler and the object (that is, the .0 file) saved. The resulting file should be placed in /usr/lib/font in the 
file ftxx where is a one or two letter code that is the logical (internal to troff) font name. This name 
can be found by looking in the file /usT/lib/fontinfo/fname* where/name is the external name of the 
font 

SEE ALSO 

fed(l), vfont(5), troff(l), vtroff(l) 

BUGS 

Produces the C file using obsolete syntax that the portable C compiler complains about. 
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NAME 

w - who is on and what they are doing 
SYNOPSIS 

w [ -h ] [ -s ] [ user ] 

DESCRIPTION 

W prints a summary of the current activity on the system, including what each user is doing. The head¬ 
ing line shows the current time of day, how long the system has been up, the number of users logged 
into the system, and the load averages. The load avCTage numbers give the number of jobs in the run 
queue averaged over 1, 5 and 15 minutes. 

The fields output are: the users login name, the name of the tty the user is on, the time of day the user 
logged on, the number of minutes since the user last typed anything, the CPU time used by all 
processes and their children on that terminal, the CPU time used by the currently active processes, the 
name and arguments of the current process. 

The -h flag suppresses the heading. The -s flag asks for a short form of output. In the short form, the 
tty is abbreviated, the login time and cpu times are left off, as are the arguments to commands. -1 
gives the long output, which is the default 

If a user name is included, the output will be restricted to that user. 

FILES 

/etc/utmp 

/dev/kmem 

/dev/drum 

SEE ALSO 

who(l), finger(l), ps(l) 

AUTHOR 

Mark Horton 

BUGS 

The notion of the “current process’’ is muddy. The current algorithm is “the highest numbered pro¬ 
cess on the terminal that is not ignoring interrupts, or, if there is none, the highest numbered process on 
the terminal’’. This fails, for example, in critical sections of programs like the shell and editor, or 
when faulty programs running in the background fork and fail to ignore interrupts. (In cases where no 
process can ^ found, w prints 

The CPU time is only an estimate, in particular, if someone leaves a background process running after 
logging out, the person currently on that terminal is “charged’’ with the time. 

Background processes are not shown, even though they account for much of the load on the system. 

Sometimes processes, typically those in the background, are printed with null or garbaged arguments. 
In these cases, the name of the command is printed in parentheses. 

W does not know about the new conventions for detection of background jobs. It will sometimes find a 
background job instead of the right one. 
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NAME 

wait - await completion of process 

SYNOPSIS 

wait 

DESCRIPTION 

Wait until all processes started with & have completed, and report on abnormal terminations. 

Because the wait{2) system call must be executed in the parent process, the Shell itself executes wait, 
without creating a new process. 

SEE ALSO 

sh(l) 

BUGS 

Not all the processes of a 3- or more-stage pipeline are children of the Shell, and thus can’t be waited 
for. (This bug does not apply to cj/i(l).) 
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NAME 

wall - write to all users 

SYNOPSIS 

wall 

DESCRIPTION 

Wall reads its standard input until an end-of-flle. It then sends this message, preceded by ‘Broadcast 
Message to all logged in users. 

The sender should be super-user to override any protections the users may have invoked. 

FILES 

/dev/tty? 

/etc/utmp 

SEE ALSO 

mesg(l), write(l) 

DIAGNOSTICS 

‘Cannot send to ...’ when the open on a user’s tty file fails. 
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NAME 

wc - word count 
SYNOPSIS 

wc [ -Iwc ] [ name ... ] 

DESCRIPTION 

Wc counts lines, words and characters in the named files, or in the standard input if no name appears. 
A word is a maximal string of charact^s delimited by spaces, tabs or newlines. 

If an argument beginning with one of “Iwc” is present, the specified counts (lines, words, or charac¬ 
ters) are selected by the letters 1, w, or c. The default is -Iwc. 

BUGS 
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NAME 

what - show what versions of object modules were used to construct a file 

SYNOPSIS 

what name ... 

DESCRIPTION 

What reads each file and searches for sequences of the form “@(#)” as inserted by the source code 
control system. It then prints the remainder of the string after this marker, up to a null character, new- 
line, double quote, or “>” character. 

BUGS 

As sees is not licensed with UNIX/32V, this is a rewrite of the what command which is part of 
sees, and may not behave exactly the same as that command does. 
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NAME 

whatis - describe what a command is 

SYNOPSIS 

whatis command... 

DESCRIPTION 

Whatis looks up a given command and gives the header line from the manual section. You can then 
run the man{\) command to get more information. If the line starts ‘name(section)...’ you can do ‘man 
section name’ to get the documentation for it Try ‘whatis ed’ and then you should do ‘man 1 ed’ to 
get the manual. 

Whatis is actually just the -f option to the man{\) command. 

FILES 

/usr/man/whatis Data base 

SEE ALSO 

man(l), catman(8) 
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NAME 

whereis - locate source, binary, and or manual for program 
SYNOPSIS 

whereis [ -sbm ] [ -u ] [ -SBM dir ... ] name ... 

DESCRIPTION 

Whereis locates source/binary and manuals sections for specified files. The supplied names are first 
stripped of leading pathname components and any (single) trailing extension of the form “.ext”, e.g. 
“.c”. Prefixes of “s.” resulting from use of source code control are also dealt with. Whereis then 
attempts to locate the desired program in a list of standard places. If any of the -b, -s or -m flags are 
given then whereis searches only for binaries, sources or manual sections respectively (or any two 
diereof). The -u flag may be used to search for unusual entries. A file is said to be unusual if it does 
not have one entry of each requested type. Thus “whereis -m -u *” asks for those files in the current 
directory which have no documentation. 

Finally, the -B -M and -S flags may be used to change or otherwise limit the places where whereis 
searches. The -f file flags is used to terminate the last such directory list and signal the start of file 
names. 

EXAMPLE 

The following finds all the files in /usr/bin which are not documented in /usr/man/manl with source in 
/usr/src/cmd: 

cd /usr/ucb 

whereis -u -M /usr/man/manl -S /usr/src/cmd -f * 

FILES 

/usr/src/* 

/usr/{doc,man}/* 

/lib, /etc, /usr/{lib,bin,ucb,old,new4ocal} 

BUGS 

Since the program uses chdir(2) to run faster, pathnames given with the -M -S and -B must be full; 
i.e. they must begin with a “/”. 
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NAME 

which - locate a program file including aliases and paths (csh only) 

SYNOPSIS 

which [ name ] ... 

DESCRIPTION 

Which takes a list of names and looks for the files which would be executed had these names been 
given as commands. Each argument is expanded if it is aliased, and searched for along the user’s path. 
Both aliases and path are taken from the user’s .cshrc file. 

FILES 

“/.cshrc source of aliases and path values 

DIAGNOSTICS 

A diagnostic is given for names which are aliased to more than a single word, or if an executable file 
with the argument name was not found in the path. 

BUGS 

Must be executed by a csh, since only csh’s know about aliases. 
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NAME 

who - who is on the system 
SYNOPSIS 

who [ who-file ] [ am I ] 

DESCRIPTION 

Who, without an argument, Usts the login name, terminal name, and login time for each current UNIX 
user. 

Without an argument, who examines the /etc/utmp file to obtain its information. If a file is given, that 
file is examined. Typically the given file will be /usr/adm/wtmp, which contains a record of all the 
logins since it was created. Then who lists logins, logouts, and crashes since the creation of the wtmp 
file. Each login is listed with user name, terminal name (with ‘/dev/’ suppressed), and date and time. 
When an argument is given, logouts produce a similar line without a user name. Reboots produce a 
line with ‘x’ in the place of the device name, and a fossil time indicative of when the system went 
down. 

With two arguments, as in ‘who am I’ (and also ‘who are you’), who tells who you are logged in as. 

FILES 

/etc/utmp 

SEE ALSO 

getuid(2), utmp(5) 


April 25, 1989 


The Wollongong Group 


1 



WHOAMI(l) 


UNIX Programmer’s Manual 


WHOAMI(l) 


NAME 

whoami - print effective current user id 

SYNOPSIS 

whoami 

DESCRIPTION 

Whoami pints who you are. It works even if you are su’d, while ‘who am i’ does not since it uses 
/etc/utmp. 

FILES 

/etc/passwd Name data base 

SEE ALSO 

who (1) 
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NOTE 


WOLLONGONG’S WIN/TCP PRODUCT 


NAME 

whois - DARPA Internet user name directory service 

SYNOPSIS 

whois name 

DESCRIPTION 

whois help 

Produces a helpful message similar to the following; 

Please enter a name ot a handle (“idem"), such as “Smith" or “SRI-NIC". Starting with a period 
forces a name-only search; starting with exclamation point forces handle-only. Examples: 

Smith [looks for name or handle SMITH ] 

ISRI-NIC [looks for handle SRI-NIC only ] 

.Smith, John [looks for name JOHN SMITH only ] 

Adding to the argument will match anything from that point, e.g. “ZU..." will match ZUL, ZUM, 
etc. 

To have the ENTIRE membership list of a group ot (organization, if you are asking about a group or 
org, shown with the record, use an asterisk character **’ directly preceding the given argument. [CAU¬ 
TION: If there are a lot of members this will take a long time!] You may of course use exclamation 
point and asterisk, or a period and asterisk together. 

EUNICE NOTES 

This file is pertinent only to customers who have Wollongong’s WIN/TCP product 
SEE ALSO 

RFC 812: NicnameAVhois 
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NOTE 


NOT PRESENT IN WOLLONGONG’S EUNICE! 


NAME 

window - window environment 
SYNOPSIS 

window [ -t ] [ -f ] [ -d ] [-e escape-char ] [ -c command ] 

DESCRIPTION 

Window implements a window environment (mi ASCII terminals. 

A window is a rectangular portion of the physical terminal screen associated with a set of processes. 
Its size and position can be changed by the user at any time. Processes communicate with their win¬ 
dow in the same way they normally interact with a terminal-through their standard input, output, and 
diagnostic file descriptors. The window program handles the details of redirecting input an output to 
and from the windows. At any one time, only one window can receive input from the keyboard, but all 
windows can simultaneously send output to the display. 

Windows can overls^ and are framed as necessary. Each window is named by one of the digits “1” to 
“9”. This one character identifier, as well as a user definable label string, are displayed with the win¬ 
dow on the top edge of its frame. A window can be designated to be in the foreground, in which case 
it will always be on top of all normal, non-foreground windows, and can be covered only by other fore¬ 
ground windows. A window need not be completely within the edges of the terminal screen. Thus a 
large window (possibly larger than the screen) may be positioned to show only a portion of its full size. 

Each window has a cursor and a set of control functions. Most intelligent terminal operations such as 
line and character deletion and insertion are supported. Display modes such as underlining and reverse 
video are available if they are supported by the terminal. In addition, siipilar to terminals with multiple 
pages of memory, each window has a text buffer which can have more lines than the window itself. 

EUNICE NOTES 

Not implemented in EUNICE. 

OPTIONS 

When window starts up, the commands (see long commands below) contained in the file .windowrc in 
the user’s home directory are executed. If it does not exist, two equal sized windows spanning the ter¬ 
minal screen are created by default. 

The command line options are 

-t Turn on terse mode (see terse command below). 

-f Fast Don’t perform any startup action. 

-d Ignore .windowrc and create the two default windows instead. 

-e escape-char 

Set the escape character to escape-char. Escape-char can be a single character, or in the form 
"X where X is any character, meaning control-X. 

-c command 

Execute the string command as a long command (see below) before doing anything else. 
PROCESS ENVIRONMENT 

With each newly created window, a shell program is spawned with its process environment tailored to 
that window. Its standard input, output, and diagnostic file descriptors are bound to one end of either a 
pseudo-terminal {pty (4)) or a UNIX domain socket {socketpair (4)). If a pseudo-terminal is used, then 
its special characters and modes (see stty (1)) are copied from the physical terminal. A termcap (5) 
entry tailored to this window is created and passed as environment {environ (5)) variable TERMCAP. 
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The termcap entry contains the window’s size and characteristics as well as information from the physi¬ 
cal terminal, such as the existence of underline, reverse video, and other display modes, and the codes 
produced by the terminal’s function keys, if any. In addition, the window size attributes of the pseudo¬ 
terminal are set to reflect the size of this window, and updated whenever it is changed by the user. In 
particular, the editor vi (1) uses this information to redraw its display. 

OPERATION 

During normal execution, window can be in one of two states: conversation mode and command mode. 
In conversation mode, the terminal’s real cursor is placed at the cursor position of a particular window- 
-called the current window~and input from the keyboard is sent to the process in that window. The 
current window is always on top of all oth^ windows, except those in foreground. In addition, it is set 
apart by highlighting its identifiCT and label in reverse video. 

Typing window's escape character (normally "P) in conversation mode switches it into command mode. 
In command mode, the top line of the terminal screen becomes the command prompt window, and win¬ 
dow interprets input from the keyboard as commands to manipulate windows. 

There are two types of commands: short commands are usually one or two key strokes; long commands 
are strings either typed by the user in the command window (see the command below), or read 
from a file (see source below). 

SHORT COMMANDS 

Below, # represents one of the digits “1” to “9” corresponding to the windows 1 to 9. means 
control-X, where X is any character. In particular, is control-". Escape is the escape key, or 

# Select window # as the current window and return to conversation mode. 

%# Select window # but stay in command mode. 

Select the previous window and return to conversation mode. This is useful for toggling 
between two windows. 

escape Return to conversation mode. 

"P Return to conversation mode and write "P to the current window. Thus, typing two "P’s in 

conversation mode sends one to the current window. If the window escape is changed to some 
other character, that character takes the place of "P here. 

? List a short summary of commands. 

"L Redraw the screen, 

q Exit window. Confirmation is requested. 

"Z Suspend window. 

w Create a new window. The user is prompted for the positions of the upper left and lower right 
comers of the window. The cursor is placed on the screen and the keys “h”, “j”, “k”, and 
“1” move the cursor left, down, up, and right, respectively. The keys “H”, “J”, “K”, and 
“L” move the cursor to the respective limits of the screen. Typing a number before the 
movement keys repeats the movement that number of times. Return enters the cursor position 
as the upper left comer of the window. The lower right comer is entered in the same manner. 
During this process, the placement of the new window is indicated by a rectangular box drawn 
on the screen, cortespon^ng to where the new window will be framed. Typing escape at any 
point cancels this command. 

This window becomes the current window, and is given the first available ID. The default 
buffer size is used (see nline command below). 

Only fully visible windows can be created this way. 

c# Close window #. The process in the window is sent the hangup signal (see kill (1)). Csh (1) 
should handle this signal correctly and cause no problems. 
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m# Move window # to another location. A box in the shape of the window is drawn on the screen 
to indicate the new position of the window, and the same keys as those for the w command are 
used to position the box. The window can be moved partially off-screen. 

M# Move window # to its previous position. 

s# Change the size of window #. The user is prompted to enter the new lower right comer of the 

window. A box is drawn to indicate the new window size. The same keys used in w and m 
are used to enter the position. 

S# Change window # to its previous size. 

Scroll the current window up by one line. 

*E Scroll the current window down by one line. 

'U Scroll the current window up by half the window size. 

"D Scroll the current window down by half the window size. 

'‘B Scroll the current window up by the full window size. 

"F Scroll the current window down by the full window size, 

h Move the cursor of the current window left by one column, 

j Move the cursor of the current window down by one line, 

k Move the cursor of the current window up by one line. 

1 Move the cursor of the current window right by one column. 

*S Stop output in the current window. 

*Q Start output in the current window. 

: Enter a line to be executed as long commands. Normal line editing characters (erase character, 

erase word, erase line) are supported. 

LONG COMMANDS 

Long commands are a sequence of statements parsed much like a programming language, with a syntax 
similar to that of C. Numeric and string expressions and variables are supported, as well as conditional 
statements. 

There are two data types: string and number. A string is a sequence of letters or digits beginning with 
a letter. and are considered letters. Alternately, non-alphanumeric characters can be included 
in strings by quoting them in or escaping them with “\”. In addition, the ‘V’ sequences of C are 
supported, both inside and outside quotes (e.g., “\n” is a new line, “Nr” a carriage return). For exam¬ 
ple, these are legal strings: abcde01234, "&#$^*&#", ab"$#"cd, abWcd, 7usr/ucb/window". 

A number is an integer value in one of three forms: a decimal number, an octal number preceded by 
“0”, or a hexadecimal number preceded by “Ox” or “OX”. The natural machine integer size is used 
(i.e., the signed integer type of the C compiler). As in C, a non-zero number represents a boolean true. 

The character “#” begins a comment which terminates at the end of the line. 

A statement is either a conditional or an expression. Expression statements are terminated with a new 
line or To continue an expression on the next line, terminate the first line with “\”. 

CONDITIONAL STATEMENT 

Window has a single control structure: the fully bracketed if statement in the form 
if <expr> then 

<statement> 

elsif <expr> then 

<statement> 
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else 

<statement> 


endif 

The else and elsif parts are optional, and the latter can be repeated any number of times. <Expr> must 
be numeric. 

EXPRESSIONS 

Expressions in window are similar to those in the C language, with most C operators supported on 
numeric operands. In addition, some are ov^loaded to operate on strings. 

When an expression is used as a statement, its value is discarded after evaluation. Therefore, only 
expressions with side effects (assignments and function calls) are useful as statements. 

Single valued (no arrays) variables are supported, of both numeric and string values. Some variables 
are predefined. They are listed below. 

The operators in order of increasing precedence: 

<exprl> = <expr2> 

Assignment. The variable of name <exprl>^ which must be string valued, is assigned the 
result of <expr2>. Returns the value of <expr2>. 

<exprl> ? <expr2> : <expr3> 

Returns the value of <expr2> if <exprl> evaluates true (non-zero numeric value); returns the 
value of <expr3> otherwise. Only one of <expr2> and <expr3> is evaluated. <Exprl> must 
be numeric. 

<exprl> II <expr2> 

Logical or. Numeric values only. Short circuit evaluation is supported (i.e., if <exprl> evalu¬ 
ates true, then <expr2> is not evaluated). 

<exprl> && <expr2> 

Logical and with short circuit evaluation. Numeric values only. 

<exprl> I <expr2> 

Bitwise or. Numeric values only. 

<exprl> * <expr2> 

Bitwise exclusive or. Numeric values only. 

<exprl> & <expr2> 

Bitwise and. Numeric values only. 

<exprl> = <expr2>, <exprl> != <expr2> 

Comparison (equal and not equal, respectively). The boolean result (either 1 or 0) of the com¬ 
parison is returned. The operands can be numeric or string valued. One string operand forces 
the other to be converted to a string in necessary. 

<exprl> < <expr2>, <exprl> > <expr2>, 

Less than, greater than, less than or equal to, greater than or equal to. Both numeric and string 
values, with automatic conversion as above. 

<exprl> « <expr2>, <exprl> » <expr2> 

If both operands are numbers, <exprl> is bit shifted left (or right) by <expr2> bits. If <exprl> 
is a string, then its first (or last) <ej^r2> characters are returns (if <expr2> is also a string, then 
its length is used in place of its value). 

<exprl> + <expr2>, <exprl> - <expr2> 

Addition and subtraction on numbers. For “+”, if one argument is a string, then the other is 
converted to a string, and the result is the concatenation of the two strings. 
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<exprl> ♦ <expr2>, <exprl> / <expr2>, 

Multiplication, division, modulo. Numbers only. 

-<expr>, "<expr>, !<expr>, $<expr>, $?<expr> 

The first three are unary minus, bitwise complement and logical complement on numbers only. 
The qwrator, “$”, takes <£xpr> and returns the value of the variable of that name. If <expr> 
is numeric with value n and it appears within an alias macro (see below), then it refers to the 
nth argument of the alias invocation. “$?” tests for the existence of the variable <expr>, and 
returns 1 if it exists or 0 otherwise. 

<expr>(<arglist>) 

Function call. <Expr> must be a string that is the unique prefix of the name of a builtin win¬ 
dow function or the full name of a user defined alias macro. In the case of a builtin function, 
<arglist> can be in one of two forms: 

<exprl>, <expr2>,... 

argnamel = <exprl>, argname2 =s <expr2>, ... 

The two forms can in fact be intermixed, but the result is unpredictable. Most arguments can 
be omitted; default values will be supplied for them. The argnames can be unique prefixes of 
the the argument names. The commas separating arguments are used only to disambiguate, 
and can usually be omitted. 

Only the first argument form is valid for user defined aliases. Aliases are defined using the 
alias builtin function (see below). Arguments are accessed via a variant of the variable 
mechanism (see “$” operator above). 

Most functions return value, but some are used for side effect only and so must be used as 
statements. When a function or an alias is used as a statement, the parenthesis surrounding the 
argument list may be omitted. Aliases return no value. 

BUILTIN FUNCTIONS 

The arguments are listed by name in their natural order. Optional arguments are in square brackets (“[ 
]”). Arguments that have no names are in angle brackets (“o’’)- 

alias([<string>], [<string-list>]) 

If no argument is given, all currently defined alias macros are listed. Otherwise, <string> is 
defined as an alias, with expansion <string-list>. The previous definition of <string>, if any, is 
returned. Default for <string-list> is no change. 

cIose(<window-list>) 

Close the windows specified in <window-list>. If <window-list> is the word all, than all win¬ 
dows are closed. No value is returned. 

cursormodes([modes]) 

Set the window cursor to modes. Modes is the bitwise or of the mode bits defined as the vari¬ 
ables m_ul (underline), m_rev (reverse video), mjblk (blinking), and m_grp (graphics, terminal 
dependent). Return value is the previous modes. Default is no change. For example, 
cursor($m_revl$m_blk) sets the window cursors to blinking reverse video. 

echo([window], [<string-list>]) 

Write the list of strings, <string-list>, to window, separated by spaces and terminated with a 
new line. The strings are only displayed in the window, the processes in the window are not 
involved (see write below). No value is returned. Default is the current window. 

escape([escapec]) 

Set the escape character to escape-char. Returns the old escape character as a one character 
string. Default is no change. Escapee can be a string of a single character, or in the form "X, 
meaning control-X. 

foreground([window], [flag]) 
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Move window in or out of foreground. Flag can be one of on, off, yes, no, true, or false, with 
obvious meanings, or it can be a numeric ejqjression, in which case a non-zero value is true. 
Returns the old foreground flag as a number. Default for window is the current window, 
default for flag is no change. 

label([window], [label]) 

Set the label of window to label. Returns the old label as a string. Default for window is the 
current window, default for label is no change. To turn off a label, set it to an empty string 

listO No arguments. List the identifiers and labels of all windows. No value is returned. 
nline([nline]) 

Set the default buffer size to nline. Initially, it is 48 lines. Returns the old default buffer size.- 
Default is no change. Using a very large buffer can slow the program down considerably. 

select([window]) 

Make window the current window. The previous current window is returned. Default is no 
change. 

shell([<struig-list>]) 

Set the default window shell program U) <string-list>. Returns the first string in the old shell 
setting. Default is no change. Initially, the default shell is taken from the environment vari¬ 
able SHELL. 

source(filename) 

Read and execute the long commands in filename. Returns -1 if the file cannot be read, 0 oth¬ 
erwise. 

terse([flag]) 

Set terse mode to flag. In terse mode, the command window stays hidden even in command 
mode, and errors are reported by sounding the terminal’s bell. Flag can take on the same 
values as in foreground above. Returns the old terse flag. Default is no change. 

unalias(alias) 

Undefine alias. Returns -1 if alias does not exist, 0 otherwise. 
unset( variable) 

Undefine variable. Returns -1 if variable does not exist, 0 otherwise. 
variablesO 

No arguments. List all variables. No value is returned. 

window([row], [column], [nrow], [ncol], [nline], [frame], 

[pty], [mapnl], [sheU]) 

Open a window with upper left comer at row, column and size nrow, ncol. If nline is 
specified, then that many lines are allocated for the text buffer. Otherwise, the default buffer 
size is used. Default values for row, column, nrow, and ncol are, respectively, the upper, left¬ 
most, lower, or right-most extremes of the screen. Frame, pty, and mapnl are flag values inter¬ 
preted in the same way as the argument to foreground (see above); they mean, respectively, 
put a frame around this window (default trae), allocate pseudo-terminal for this window rather 
than socketpair (default tme), and map new line characters in this window to carriage return 
and line feed (default true if socketpair is used, false otherwise). Shell is a list of strings that 
will be used as the shell program to place in the window (default is the program specified by 
shell, see below). The created window’s identifier is returned as a number. 

write([window], [<string-list>]) 

Send the list of strings, <string-list>, to window, separated by spaces but not terminated with a 
new line. The strings are actually given to the window as input. No value is returned. 
Default is the current window. 
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PREDEFINED VARIABLES 

These variables are for information only. Redefining them does not affect the internal operation of win¬ 
dow. 

baud The baud rate as a number between 50 and 38400. 

modes The display modes (reverse video, underline, blinking, graphics) supported by the physical ter¬ 
minal. The value of modes is the bitwise or of some of the one bit values, m_blk, m_grp, 
m_rev, and m_ul (see below). These values are useful in setting the window cursors’ modes 
(see cursormodes above). 

m_blk The blinking mode bit. 

m_grp The graphics mode bit (not very useful). 

m_rev The reverse video mode bit. 

m_ul The underline mode bit 

ncol The number of columns on the physical screen. 

nrow The number of rows on the physical screen. 

term The terminal type. The standard name, found in the second name field of the terminal’s 
TERMCAP entry, is used. 

FILES 

"■/.windowrc startup command file. 

/dev/[pt]ty[pq]? pseudo-terminal devices. 

DIAGNOSTICS 

Should be self explanatory. 

BUGS 
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NAME 

write - write to another user 
SYNOPSIS 

write user [ ttyname ] 

DESCRIPTION 

Write copies lines from your terminal to that of another user. When first called, it sends the message 
Message from youmame@yoursystem on yourttyname at time... 

The recipient of the message should write back at this point Communication continues until an end of 
file is read from the terminal or an interrupt is sent At that point write writes ‘EOT’ on the other ter¬ 
minal and exits. 

If you want to write to a user who is logged in more than once, the ttyname argument may be used to 
indicate the appropriate terminal name. 

Permission to write may be denied or granted by use of the mesg command. At the outset writing is 
allowed. Certain commands, in particular nroff and pr(l) disallow messages in order to prevent messy 
output 

If the character *!’ is found at the beginning of a line, write calls the shell to execute the rest of the line 
as a command. 

The following protocol is suggested for using write: when you first write to another user, wait for him 
to write back ^fore starting to send. Each party should end each message with a distinctive signal— 
(o) for ‘over’ is conventional—that the other may reply, (oo) for ‘over and out’ is suggested when 
conversation is about to be terminated. 

FILES 

/etc/utmp to find user 

/bin/sh to execute ‘!’ 

SEE ALSO 

mesg(l), who(l), mail(l) 
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NAME 

xsend, xget, enroll - secret mail 

SYNOPSIS 

xsend person 

xget 

enroll 

DESCRIPTION 

These commands implement a secure communication channel; it is like but no one can read 

the messages except the intended recipient. The method embodies a public-key cryptosystem using 
knapsacks. 

To receive messages, use enroll \ it asks you for a password that you must subsequently quote in order 
to receive secret mail. 

To receive secret mail, use xget. It asks for your password, then gives you the messages. 

To send secret mail, use xsend in the same manner as the ordinary mail command. (However, it will 
accept only one target). A message announcing the receipt of secret mail is also sent by ordinary mail. 

FILES 

/usr/spool/secretmail/*Jcey; keys 
/usr/spooI/secretmail/*.[0-9]: messages 

SEE ALSO 

mail (1) 

BUGS 

It should be integrated with ordinary mail. The announcement of secret mail makes traffic analysis pos¬ 
sible. 
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NAME 

xstr - extract strings from C programs to implement shared strings 
SYNOPSIS 

xstr [ -c ] [ - ] [ file ] 

DESCRIPTION 

Xstr maintains a file strings into which strings in component parts of a large program are hashed. 
These strings are replaced with references to this common area. This serves to implement shared con¬ 
stant strings, most useful if they are also read-only. 

The command 

xstr -c name 

will extract the strings from the C source in name, replacing string references by expressions of the 
form (&xstr[number]) for some number. An appropriate declaration of xstr is prepended to the file. 
The resulting C text is placed in the file x.c, to then be compiled. The strings from this file are placed 
in the strings data base if they are not there already. Repeated strings and strings which are suffices of 
existing strings do not cause changes to the data base. 

After all components of a large program have been compiled a file xsx declaring the common xstr 
space can be created by a command of the form 

xstr 

This xs.c file should then be compiled and loaded with the rest of the program. If possible, the array 
can be made read-only (shared) saving space and swap overhead. 

Xstr can also be used on a single file. A command 

xstr name 

creates files x.c and xs.c as before, without using or affecting any strings file in the same directory. 

It may be useful to run xstr after the C preprocessor if any macro definitions yield strings or if there is 
conditional code which contains strings which may not, in fact, be needed. Xstr reads from its standard 
input when the argument is given. An appropriate command sequence for running xstr after the C 
preprocessor is: 

cc -E name.c I xstr -c - 
cc -c x.c 
mv x.o name.o 

Xstr does not touch the file strings unless new items are added, thus make can avoid remaking xs.o 
unless truly necessary. 

FILES 

strings Data base of strings 

x.c Massaged C source 

xs.c C source for definition of array ‘xstr’ 

/tmp/xs*Temp file when ‘xstr name’ doesn’t touch strings 

SEE ALSO 

mkstr(l) 

BUGS 

If a string is a suffix of another string in the data base, but the shorter string is seen first by xstr both 
strings will be placed in the data base, when just placing the longer one there will do. 
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NAME 

yacc - yet another compiler-compiler 
SYNOPSIS 

yacc [ -vd ] grammar 
DESCRIPTION 

Yacc converts a context-free grammar into a set of tables for a simple automaton which executes an 
LR(1) parsing algorithm. The grammar may be ambiguous; specified precedence rules are used to 
break ambiguities. 

The output file, y.tab.c^ must be compiled by the C compiler to produce a program yyparse. This pro¬ 
gram must be loaded with the lexical analyzer program, yylex^ as well as main and yyerror, an error 
handling routine. These routines must be supplied by the user; Lex(l) is useful for creating lexical 
analyzers usable by yacc. 

If the -V flag is given, the file y.output is prepared, which contains a description of the parsing tables 
and a report on conflicts generated by ambiguities in the grammar. 

If the -d flag is used, the file y.tab.h is generated with the define statements that associate the yacc- 
assigned ‘token codes* with the user-declared ‘token names’. This allows source files other than y.tab.c 
to access the token codes. 

FILES 

y.output 

y.tab.c 

y.tab.h defines for token names 

yacc.tmp, yacc.acts temporary files 
/usr/lib/yaccpar parser prototype for C programs 

SEE ALSO 

lex(l) 

LR Parsing by A. V. Aho and S. C. Johnson, Compiuing Surveys, June, 1974. 

YACC - Yet Another Compiler Compiler by S. C. Johnson. 

DIAGNOSTICS 

The number of reduce-reduce and shift-reduce conflicts is reported on the standard output; a more 
detailed report is found in the y.output file. Similarly, if some rules are not reachable from the start 
symbol, this is also reported. 

BUGS 

Because file names are fixed, at most one yacc process can be active in a given directory at a time. 


April 25, 1989 


The Wollongong Group 


1 



YES(l) 


UNIX Programmer’s Manual 


YES(l) 


NAME 

yes - be repetitively affirmative 

SYNOPSIS 

yes [ expletive ] 

DESCRIPTION 

Yes repeatedly outputs “y”, or if expletive is given, that is output repeatedly. Termination is by rubouL 
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